From 66c1e6d35579697209910746703a6525b0e25e3b Mon Sep 17 00:00:00 2001 From: Nikita Kovaliov Date: Mon, 19 Aug 2024 14:05:49 +0300 Subject: [PATCH] Complete javadocs documentation for some classes --- .../pdfa/validation/profiles/Profiles.java | 74 ++++++++----------- .../verapdf/processor/plugins/Attribute.java | 68 ++++++++++------- .../containers/StaticXmpCoreContainers.java | 26 ++++++- .../VeraPDFExtensionSchemaDefinition.java | 69 ++++++++++++++--- .../java/org/verapdf/xmp/impl/XMPNode.java | 18 +++-- 5 files changed, 172 insertions(+), 83 deletions(-) diff --git a/core/src/main/java/org/verapdf/pdfa/validation/profiles/Profiles.java b/core/src/main/java/org/verapdf/pdfa/validation/profiles/Profiles.java index ef90aed81..5d2ea19cb 100644 --- a/core/src/main/java/org/verapdf/pdfa/validation/profiles/Profiles.java +++ b/core/src/main/java/org/verapdf/pdfa/validation/profiles/Profiles.java @@ -311,25 +311,20 @@ public static Rule ruleFromValues(final RuleId id, final String object, final St /** * Returns a {@link Rule} instance initialised with the passed values. * - * @param id - * the {@link RuleId} id for the {@link Rule} - * @param object - * a String that identifies the Object that the rule applies to - * @param deferred - * a Boolean that identifies the deferred property of the rule - * @param description - * a textual description of the {@link Rule}. - * @param test - * a JavaScript expression that is the test carried out on a - * model instance - * @param error - * the {@link ErrorDetails} associated with the{@link Rule}. - * @param references - * a list of further {@link Reference}s for this rule + * @param id the {@link RuleId} id for the {@link Rule} + * @param object a String that identifies the Object that the rule applies to + * @param deferred a Boolean that identifies the deferred property of the rule + * @param tags a String that contains comma-separated list of tags associated with this rule + * @param description a textual description of the {@link Rule}. + * @param test a JavaScript expression that is the test carried out on a + * model instance + * @param error the {@link ErrorDetails} associated with the{@link Rule}. + * @param references a list of further {@link Reference}s for this rule + * * @return a {@link Rule} instance. - * @throws IllegalArgumentException - * if any of the parameters are null or the test, object, or - * description is empty + * + * @throws IllegalArgumentException if any of the parameters are null or the test, object, or + * description is empty */ public static Rule ruleFromValues(final RuleId id, final String object, final Boolean deferred, String tags, final String description, final String test, @@ -409,6 +404,7 @@ public static Variable variableFromValues(final String name, final String object * @param toConvert a {@link ValidationProfile} to convert to an XML String * @param format set to Boolean.TRUE for pretty formatted XML, Boolean.FALSE * for no space formatting + * @param fragment a flag to generate document level events * * @return a String xml representation of toConvert * @@ -427,18 +423,15 @@ public static String profileToXml(final ValidationProfile toConvert, boolean for * Convert a {@link ValidationProfile} instance to XML and serialise to the * {@link OutputStream} forXMLOutput. * - * @param toConvert - * a {@link ValidationProfile} to convert to an XML String - * @param dest - * an OutputStream used to write the generated XML to - * @param format - * 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 - * @throws IllegalArgumentException - * if toConvert is null + * @param toConvert a {@link ValidationProfile} to convert to an XML String + * @param dest an OutputStream used to write the generated XML to + * @param format set to Boolean.TRUE for pretty formatted XML, Boolean.FALSE + * for no space formatting + * @param fragment a flag to generate document level events + * + * @throws JAXBException thrown by JAXB marshaller if there's an error converting the + * object + * @throws IllegalArgumentException if toConvert is null */ public static void profileToXml(final ValidationProfile toConvert, final OutputStream dest, boolean format, boolean fragment) throws JAXBException { @@ -470,18 +463,15 @@ public static ValidationProfile profileFromXml(final InputStream source) throws * Convert a {@link ValidationProfile} instance to XML and serialise to the * {@link Writer} forXMLOutput. * - * @param toConvert - * a {@link ValidationProfile} to convert to an XML String - * @param dest - * a Writer used to write the generated XML to - * @param format - * 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 - * @throws IllegalArgumentException - * if toConvert is null + * @param toConvert a {@link ValidationProfile} to convert to an XML String + * @param dest a Writer used to write the generated XML to + * @param format set to Boolean.TRUE for pretty formatted XML, Boolean.FALSE + * for no space formatting + * @param fragment a flag to generate document level events + * + * @throws JAXBException thrown by JAXB marshaller if there's an error converting the + * object + * @throws IllegalArgumentException if toConvert is null */ public static void profileToXml(final ValidationProfile toConvert, Writer dest, boolean format, boolean fragment) throws JAXBException { diff --git a/core/src/main/java/org/verapdf/processor/plugins/Attribute.java b/core/src/main/java/org/verapdf/processor/plugins/Attribute.java index e33a5e30f..dcebfb176 100644 --- a/core/src/main/java/org/verapdf/processor/plugins/Attribute.java +++ b/core/src/main/java/org/verapdf/processor/plugins/Attribute.java @@ -29,29 +29,47 @@ @XmlRootElement(name = "attribute") public class Attribute { - @XmlAttribute - private final String key; - @XmlAttribute - private final String value; - - private Attribute(String key, String value) { - this.key = key; - this.value = value; - } - - private Attribute() { - this("", ""); - } - - public static Attribute fromValues(String key, String value) { - return new Attribute(key, value); - } - - public String getKey() { - return key; - } - - public String getValue() { - return value; - } + @XmlAttribute + private final String key; + @XmlAttribute + private final String value; + + private Attribute(String key, String value) { + this.key = key; + this.value = value; + } + + private Attribute() { + this("", ""); + } + + /** + * Creates attribute key and value. + * + * @param key an attribute key + * @param value an attribute value + * + * @return an attribute a pair of key and value + */ + public static Attribute fromValues(String key, String value) { + return new Attribute(key, value); + } + + /** + * Gets attribute key. + * + * @return an attribute key + */ + public String getKey() { + return key; + } + + /** + * Gets attribute value. + * + * @return an attribute value + */ + public String getValue() { + return value; + } } diff --git a/xmp-core/src/main/java/org/verapdf/xmp/containers/StaticXmpCoreContainers.java b/xmp-core/src/main/java/org/verapdf/xmp/containers/StaticXmpCoreContainers.java index b00767f69..b8a48476e 100644 --- a/xmp-core/src/main/java/org/verapdf/xmp/containers/StaticXmpCoreContainers.java +++ b/xmp-core/src/main/java/org/verapdf/xmp/containers/StaticXmpCoreContainers.java @@ -1,6 +1,7 @@ package org.verapdf.xmp.containers; -import java.util.*; +import java.util.HashMap; +import java.util.Map; public class StaticXmpCoreContainers { @@ -14,23 +15,46 @@ public class StaticXmpCoreContainers { */ private static final ThreadLocal> prefixToNamespaceMap = new ThreadLocal<>(); + /** + * Clears all namespaces and prefixes. + */ public static void clearAllContainers() { namespaceToPrefixMap.set(new HashMap<>()); prefixToNamespaceMap.set(new HashMap<>()); } + /** + * Gets namespaces map. + * + * @return a map of namespaces + */ public static Map getNamespaceToPrefixMap() { return namespaceToPrefixMap.get(); } + /** + * Gets prefixes map. + * + * @return a map of prefixes + */ public static Map getPrefixToNamespaceMap() { return prefixToNamespaceMap.get(); } + /** + * Sets namespaces. + * + * @param namespaceToPrefixMap a map of namespaces + */ public static void setNamespaceToPrefixMap(Map namespaceToPrefixMap) { StaticXmpCoreContainers.namespaceToPrefixMap.set(namespaceToPrefixMap); } + /** + * Sets prefixes. + * + * @param prefixToNamespaceMap a map of prefixes + */ public static void setPrefixToNamespaceMap(Map prefixToNamespaceMap) { StaticXmpCoreContainers.prefixToNamespaceMap.set(prefixToNamespaceMap); } diff --git a/xmp-core/src/main/java/org/verapdf/xmp/impl/VeraPDFExtensionSchemaDefinition.java b/xmp-core/src/main/java/org/verapdf/xmp/impl/VeraPDFExtensionSchemaDefinition.java index de41d1152..5000ac795 100644 --- a/xmp-core/src/main/java/org/verapdf/xmp/impl/VeraPDFExtensionSchemaDefinition.java +++ b/xmp-core/src/main/java/org/verapdf/xmp/impl/VeraPDFExtensionSchemaDefinition.java @@ -1,27 +1,36 @@ package org.verapdf.xmp.impl; -import org.verapdf.xmp.XMPConst; -import org.verapdf.xmp.XMPException; -import org.verapdf.xmp.options.PropertyOptions; - import java.util.ArrayList; import java.util.Collections; import java.util.List; +import org.verapdf.xmp.XMPConst; +import org.verapdf.xmp.XMPException; +import org.verapdf.xmp.options.PropertyOptions; public class VeraPDFExtensionSchemaDefinition { private static final String PROPERTY = "property"; - public static final String NAMESPACE_URI = "namespaceURI"; + private static final String NAMESPACE_URI = "namespaceURI"; private static final String PREFIX = "prefix"; private static final String SCHEMA = "schema"; private static final String PDFA_SCHEMA_PREFIX = "pdfaSchema"; private final VeraPDFXMPNode xmpNode; + /** + * VeraPDF extension schema. + * + * @param xmpNode a metadata node + */ public VeraPDFExtensionSchemaDefinition(VeraPDFXMPNode xmpNode) { this.xmpNode = xmpNode; } + /** + * Gets schema properties. + * + * @return schema properties + */ public List getExtensionSchemaProperties() { if (this.xmpNode != null) { List res = new ArrayList<>(); @@ -39,7 +48,12 @@ public List getExtensionSchemaProperties() { } return Collections.emptyList(); } - + + /** + * Gets property of xmp node. + * + * @return xmp node property value + */ public VeraPDFXMPNode getPropertiesNode() { if (this.xmpNode != null) { for (VeraPDFXMPNode child : this.xmpNode.getChildren()) { @@ -51,12 +65,25 @@ public VeraPDFXMPNode getPropertiesNode() { return null; } - public void addExtensionSchemaProperty(VeraPDFExtensionSchemaProperty propertyDefinitionXMPNode) throws XMPException { + /** + * Adds extension schema property. + * + * @param propertyDefinitionXMPNode a property of xmp node + * + * @throws XMPException exceptions from the metadata processing + */ + public void addExtensionSchemaProperty(VeraPDFExtensionSchemaProperty propertyDefinitionXMPNode) + throws XMPException { if (this.xmpNode != null) { getPropertiesNode().getOriginalNode().addChild(propertyDefinitionXMPNode.getXmpNode()); } } + /** + * Gets namespaces URI of xmp node. + * + * @return xmp node namespace value + */ public String getNamespaceURI() { for (VeraPDFXMPNode child : this.xmpNode.getChildren()) { if (XMPConst.NS_PDFA_SCHEMA.equals(child.getNamespaceURI()) && NAMESPACE_URI.equals(child.getName())) { @@ -66,6 +93,11 @@ public String getNamespaceURI() { return null; } + /** + * Gets prefix of xmp node. + * + * @return xmp node prefix value + */ public String getPrefix() { for (VeraPDFXMPNode child : this.xmpNode.getChildren()) { if (XMPConst.NS_PDFA_SCHEMA.equals(child.getNamespaceURI()) && PREFIX.equals(child.getName())) { @@ -75,19 +107,36 @@ public String getPrefix() { return null; } + /** + * Gets xmp node. + * + * @return original xmp node from metadata + */ public XMPNode getXmpNode() { return xmpNode.getOriginalNode(); } - public static VeraPDFExtensionSchemaDefinition createExtensionSchemaDefinitionNode(String schema, String namespaceURI, String prefix) throws XMPException { - XMPNode node = new XMPNode(XMPConst.ARRAY_ITEM_NAME,"", new PropertyOptions(PropertyOptions.STRUCT), "rdf"); + /** + * Creates schema definition node. + * + * @param schema a xmp schema definition + * @param namespaceURI a namespace URI of the node + * @param prefix a prefix of the node + * + * @return xmp extension schema + * + * @throws XMPException exceptions from the metadata processing + */ + public static VeraPDFExtensionSchemaDefinition createExtensionSchemaDefinitionNode(String schema, + String namespaceURI, String prefix) throws XMPException { + XMPNode node = new XMPNode(XMPConst.ARRAY_ITEM_NAME, "", new PropertyOptions(PropertyOptions.STRUCT), "rdf"); node.addChild(new XMPNode(PDFA_SCHEMA_PREFIX + ":" + SCHEMA, schema, new PropertyOptions(PropertyOptions.NO_OPTIONS), PDFA_SCHEMA_PREFIX)); node.addChild(new XMPNode(PDFA_SCHEMA_PREFIX + ":" + NAMESPACE_URI, namespaceURI, new PropertyOptions(PropertyOptions.NO_OPTIONS), PDFA_SCHEMA_PREFIX)); node.addChild(new XMPNode(PDFA_SCHEMA_PREFIX + ":" + PREFIX, prefix, new PropertyOptions(PropertyOptions.NO_OPTIONS), PDFA_SCHEMA_PREFIX)); - node.addChild(new XMPNode(PDFA_SCHEMA_PREFIX + ":" + PROPERTY,"", + node.addChild(new XMPNode(PDFA_SCHEMA_PREFIX + ":" + PROPERTY, "", new PropertyOptions(PropertyOptions.ARRAY + PropertyOptions.ARRAY_ORDERED), PDFA_SCHEMA_PREFIX)); return new VeraPDFExtensionSchemaDefinition(VeraPDFXMPNode.fromXMPNode(node)); } diff --git a/xmp-core/src/main/java/org/verapdf/xmp/impl/XMPNode.java b/xmp-core/src/main/java/org/verapdf/xmp/impl/XMPNode.java index 8e9dbf632..587d6b8dc 100644 --- a/xmp-core/src/main/java/org/verapdf/xmp/impl/XMPNode.java +++ b/xmp-core/src/main/java/org/verapdf/xmp/impl/XMPNode.java @@ -65,9 +65,10 @@ public class XMPNode implements Comparable /** * Creates an XMPNode with initial values. * - * @param name the name of the node - * @param value the value of the node - * @param options the options of the node + * @param name the name of the node + * @param value the value of the node + * @param options the options of the node + * @param originalPrefix the original prefix of the node */ public XMPNode(String name, String value, PropertyOptions options, String originalPrefix) { @@ -82,8 +83,9 @@ public XMPNode(String name, String value, PropertyOptions options, String origin /** * Constructor for the node without value. * - * @param name the name of the node - * @param options the options of the node + * @param name the name of the node + * @param options the options of the node + * @param originalPrefix the original prefix of the node */ public XMPNode(String name, PropertyOptions options, String originalPrefix) { @@ -91,6 +93,12 @@ public XMPNode(String name, PropertyOptions options, String originalPrefix) } //------------------------------------------------------------------------------ veraPDF: getter method for original prefix + + /** + * Gets original prefix of xmp node. + * + * @return an original prefix of xmp node + */ public String getOriginalPrefix() { return this.originalPrefix; }