org.verapdf.pdfa.validation.profiles

Class Profiles

java.lang.Object

org.verapdf.pdfa.validation.profiles.Profiles

public final class Profiles
extends Object

Utitlity class that provides helper methods for handling ValidationProfiles and associated classes.

The utility methods generally fall into one of the following categories:

• default instance creators, defaultTypeName(), used for testing or when a vanilla instance of a particular type is required.
• from values instance creators, typeNameFromValues(...), used to create instances from their contained types.
• XML helper methods, typeNameToXml(...), to facilitate XML serialisation to Strings, OutputStreams and Writers.
• XML helper methods, typeNameFromXml(...), to facilitate XML deserialisation.

Note that XML serialisation and de-serialisation is achieved through JAXB bindings.

TODO: Defensive Checks for all parameters.

Author:

Carl Wilson

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Profiles.RuleComparator
static class	Profiles.RuleIdComparator

Constructor Summary

Constructors

Constructor and Description
Profiles()

Method Summary

Modifier and Type	Method and Description
static ErrorDetails	defaultError() Returns an immutable default instance of ErrorDetails.
static ValidationProfile	defaultProfile() Returns an immutable default instance of a ValidationProfile.
static Reference	defaultReference() Returns an immutable default instance of a Reference.
static Rule	defaultRule() Returns an immutable default instance of a Rule.
static RuleId	defaultRuleId() Returns an immutable default instance of a RuleId.
static Variable	defaultVariable() Returns an immutable default instance of a Variable.
static ProfileDirectory	directoryFromProfiles(Set<ValidationProfile> profiles) Create a ProfileDirectory from a Set of ValidationProfiles.
static ErrorDetails	errorFromValues(String message, List<String> arguments) Returns a ErrorDetails instance initialised with the passed values.
static String	getValidationProfileSchema() Returns the JAXB generated XML schema for the ValidationProfileImpl type.
static ProfileDirectory	getVeraProfileDirectory() Returns a ProfileDirectory instance that has been pre-populated with the curated ValidationProfiles supplied with the veraPDF library.
static ProfileDetails	profileDetailsFromValues(String name, String description, String creator, Date created) Returns a ProfileDetails instance initialised using the passed values.
static ValidationProfile	profileFromSortedValues(PDFAFlavour flavour, ProfileDetails details, String hash, SortedSet<Rule> rules, Set<Variable> variables) Returns a ValidationProfile instance initialised with the passed values.
static ValidationProfile	profileFromValues(PDFAFlavour flavour, ProfileDetails details, String hash, Set<Rule> rules, Set<Variable> variables) Returns a ValidationProfile instance initialised with the passed values.
static ValidationProfile	profileFromXml(InputStream source) Attempt to de-serialise and return a ValidationProfile instance from an XML representation that can be read from toConvert.
static String	profileToXml(ValidationProfile toConvert, boolean format, boolean fragment) Convert a ValidationProfile instance into an XML String.
static void	profileToXml(ValidationProfile toConvert, OutputStream dest, boolean format, boolean fragment) Convert a ValidationProfile instance to XML and serialise to the OutputStream forXMLOutput.
static void	profileToXml(ValidationProfile toConvert, Writer dest, boolean format, boolean fragment) Convert a ValidationProfile instance to XML and serialise to the Writer forXMLOutput.
static Reference	referenceFromValues(String specification, String clause) Returns a Reference instance initialised with the passed values.
static Rule	ruleFromValues(RuleId id, String object, Boolean deferred, String description, String test, ErrorDetails error, List<Reference> references) Returns a Rule instance initialised with the passed values.
static Rule	ruleFromValues(RuleId id, String object, String description, String test, ErrorDetails error, List<Reference> references) Returns a Rule instance initialised with the passed values.
static RuleId	ruleIdFromValues(PDFAFlavour.Specification specification, String clause, int testNumber) Returns a RuleId instance initialised with the passed values.
static Variable	variableFromValues(String name, String object, String defaultValue, String value) Returns a Variable instance initialised with the passed values.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Profiles

public Profiles()

Method Detail

profileFromValues

public static ValidationProfile profileFromValues(PDFAFlavour flavour,
                                                  ProfileDetails details,
                                                  String hash,
                                                  Set<Rule> rules,
                                                  Set<Variable> variables)

Returns a ValidationProfile instance initialised with the passed values.

Parameters:

flavour - the PDF/A flavour supported by this profile represented as a PDFAFlavour instance.

details - the ProfileDetails for the profile.

hash - an identifying hash for the profile

rules - the Set of Rules for the profile

variables - the Set of Variables for the profile

Returns:

a new ValidationProfile instance.

Throws:

IllegalArgumentException - if any of the passed parameters are null or if any of name, description or creator are empty.

profileFromSortedValues

public static ValidationProfile profileFromSortedValues(PDFAFlavour flavour,
                                                        ProfileDetails details,
                                                        String hash,
                                                        SortedSet<Rule> rules,
                                                        Set<Variable> variables)

Returns a ValidationProfile instance initialised with the passed values.

Parameters:

flavour - the PDF/A flavour supported by this profile represented as a PDFAFlavour instance.

details - the ProfileDetails for the profile.

hash - an identifying hash for the profile

rules - the Set of Rules for the profile

variables - the Set of Variables for the profile

Returns:

a new ValidationProfile instance.

Throws:

IllegalArgumentException - if any of the passed parameters are null or if any of name, description or creator are empty.

defaultProfile

public static ValidationProfile defaultProfile()

Returns an immutable default instance of a ValidationProfile. This is a static single instance, i.e. Profiles.defaultProfile() == Profiles.defaultProfile() is always true.

Returns:

the ValidationProfile default instance

profileDetailsFromValues

public static ProfileDetails profileDetailsFromValues(String name,
                                                      String description,
                                                      String creator,
                                                      Date created)

Returns a ProfileDetails instance initialised using the passed values.

Parameters:

name - a String name that identifies the profile

description - a short, textual String description of the profile.

creator - a String that identifies the creator of the profile

created - a Date instance indicating when the profile was created.

Returns:

the ProfileDetails instance initialised from the values

defaultReference

public static Reference defaultReference()

Returns an immutable default instance of a Reference. This is a static single instance, i.e. Profiles.defaultReference() == Profiles.defaultReference() is always true.

Returns:

the Reference default instance

referenceFromValues

public static Reference referenceFromValues(String specification,
                                            String clause)

Returns a Reference instance initialised with the passed values.

Parameters:

specification - a String identifying the specification the Reference refers to.

clause - a String identifying the location referred to within the specification.

Returns:

an appropriately initialised Reference instance

Throws:

IllegalArgumentException - if any of the parameters are null or the specification is empty

defaultRuleId

public static RuleId defaultRuleId()

Returns an immutable default instance of a RuleId. This is a static single instance, i.e. Profiles.defaultRuleId() == Profiles.defaultRuleId() is always true.

Returns:

the RuleId default instance

ruleIdFromValues

public static RuleId ruleIdFromValues(PDFAFlavour.Specification specification,
                                      String clause,
                                      int testNumber)

Returns a RuleId instance initialised with the passed values.

Parameters:

specification - a PDFAFlavour.Specification instance identifying the PDF/A specification part the RuleId is derived

clause - a String that identifies that clause within the specification that the RuleId is derived

testNumber - an int that identifies the test number for the RuleId

Returns:

a RuleId instance

Throws:

IllegalArgumentException - if any of the parameters are null or the clause is empty

defaultRule

public static Rule defaultRule()

Returns an immutable default instance of a Rule. This is a static single instance, i.e. Profiles.defaultRule() == Profiles.defaultRule() is always true.

Returns:

the Rule default instance

defaultError

public static ErrorDetails defaultError()

Returns an immutable default instance of ErrorDetails. This is a static single instance, i.e. Profiles.defaultError() == Profiles.defaultError() is always true.

Returns:

the ErrorDetails default instance

errorFromValues

public static ErrorDetails errorFromValues(String message,
                                           List<String> arguments)

Returns a ErrorDetails instance initialised with the passed values.

Parameters:

message - a String message for the ErrorDetails

arguments - a List of String arguments for the ErrorDetails.

Returns:

an ErrorDetails instance

Throws:

IllegalArgumentException - if any of the parameters are null or message is empty

ruleFromValues

public static Rule ruleFromValues(RuleId id,
                                  String object,
                                  String description,
                                  String test,
                                  ErrorDetails error,
                                  List<Reference> references)

Returns a Rule instance initialised with the passed values.

Parameters:

id - the RuleId id for the Rule

object - a String that identifies the Object that the rule applies to

description - a textual description of the Rule.

test - a JavaScript expression that is the test carried out on a model instance

error - the ErrorDetails associated with theRule.

references - a list of further References for this rule

Returns:

a Rule instance.

Throws:

IllegalArgumentException - if any of the parameters are null or the test, object, or description is empty

ruleFromValues

public static Rule ruleFromValues(RuleId id,
                                  String object,
                                  Boolean deferred,
                                  String description,
                                  String test,
                                  ErrorDetails error,
                                  List<Reference> references)

Returns a Rule instance initialised with the passed values.

Parameters:

id - the RuleId id for the Rule

object - a String that identifies the Object that the rule applies to

deferred - a Boolean that identifies the deferred property of the rule

description - a textual description of the Rule.

test - a JavaScript expression that is the test carried out on a model instance

error - the ErrorDetails associated with theRule.

references - a list of further References for this rule

Returns:

a Rule instance.

Throws:

IllegalArgumentException - if any of the parameters are null or the test, object, or description is empty

defaultVariable

public static Variable defaultVariable()

Returns an immutable default instance of a Variable. This is a static single instance, i.e. Profiles.defaultVariable() == Profiles.defaultVariable() is always true.

Returns:

the Variable default instance

variableFromValues

public static Variable variableFromValues(String name,
                                          String object,
                                          String defaultValue,
                                          String value)

Returns a Variable instance initialised with the passed values.

Parameters:

name - a name for the Variable

object - a String identifying the object type for the Variable

defaultValue - a String default value for the Variable

value - a value for the for the Variable

Returns:

a new Variable instance

Throws:

IllegalArgumentException - if any of the parameters are null or empty

profileToXml

public static String profileToXml(ValidationProfile toConvert,
                                  boolean format,
                                  boolean fragment)
                           throws JAXBException

Convert a ValidationProfile instance into an XML String.

Parameters:

toConvert - a ValidationProfile to convert to an XML String

prettyXml - set to Boolean.TRUE for pretty formatted XML, Boolean.FALSE for no space formatting

Returns:

a String xml representation of toConvert

Throws:

JAXBException - thrown by JAXB marshaller if there's an error converting the object

IOException - thrown when's there's a problem closing the underlying StringWriter

IllegalArgumentException - if toConvert is null

profileToXml

public static void profileToXml(ValidationProfile toConvert,
                                OutputStream dest,
                                boolean format,
                                boolean fragment)
                         throws JAXBException

Convert a ValidationProfile instance to XML and serialise to the OutputStream forXMLOutput.

Parameters:

toConvert - a ValidationProfile to convert to an XML String

forXmlOutput - an OutputStream used to write the generated XML to

prettyXml - set to Boolean.TRUE for pretty formatted XML, Boolean.FALSE for no space formatting

Throws:

JAXBException - thrown by JAXB marshaller if there's an error converting the object

IllegalArgumentException - if toConvert is null

profileFromXml

public static ValidationProfile profileFromXml(InputStream source)
                                        throws JAXBException

Attempt to de-serialise and return a ValidationProfile instance from an XML representation that can be read from toConvert.

Parameters:

toConvert - an InputStream to an XML representation of a profile

Returns:

a new ValidationProfile instance

Throws:

JAXBException - thrown by JAXB marshaller if there's an error converting the object

IllegalArgumentException - if toConvert is null

profileToXml

public static void profileToXml(ValidationProfile toConvert,
                                Writer dest,
                                boolean format,
                                boolean fragment)
                         throws JAXBException

Convert a ValidationProfile instance to XML and serialise to the Writer forXMLOutput.

Parameters:

toConvert - a ValidationProfile to convert to an XML String

forXmlOutput - a Writer used to write the generated XML to

prettyXml - set to Boolean.TRUE for pretty formatted XML, Boolean.FALSE for no space formatting

Throws:

JAXBException - thrown by JAXB marshaller if there's an error converting the object

IllegalArgumentException - if toConvert is null

directoryFromProfiles

public static ProfileDirectory directoryFromProfiles(Set<ValidationProfile> profiles)

Create a ProfileDirectory from a Set of ValidationProfiles. Note that the returned directory uses each ValidationProfile's associated PDFAFlavour as a directory key. This means that only a single ValidationProfile can be associated with a particular PDFAFlavour. If the Set of Profiles passed in profiles contains multiple ValidationProfiles with the same PDFAFlavour only one will be contained in the returned ProfileDirectory. Which one is indeterminate.

Parameters:

profiles - a Set of ValidationProfiles used to populate the directory instance

Returns:

a ProfileDirectory populated with the ValidationProfiles passed in the profiles parameter

Throws:

IllegalArgumentException - if the profiles parameter is null or empty

getVeraProfileDirectory

public static ProfileDirectory getVeraProfileDirectory()

Returns a ProfileDirectory instance that has been pre-populated with the curated ValidationProfiles supplied with the veraPDF library.

While the veraPDF library and associated ValidationProfiles are under development, there is no guarantee that the profiles supplied are complete and accurate. Please check the validation profiles GitHub repo to find out the current status of our ValidationProfiles.

Returns:

the pre-populated veraPDF ValidationProfile directory

getValidationProfileSchema

public static String getValidationProfileSchema()
                                         throws JAXBException,
                                                IOException

Returns the JAXB generated XML schema for the ValidationProfileImpl type.

Returns:

the String representation of the schema

Throws:

JAXBException - if there's a problem marshaling the schema

IOException - if there's a problem outputting the result