From ae23cb5e344291be469c0f755d4eee4299807a69 Mon Sep 17 00:00:00 2001 From: bobcat_zed Date: Wed, 19 Mar 2008 09:55:47 +0000 Subject: [PATCH] Fleshed out the Javadocs for a bunch of classes in se.kb.oai.ore.* and se.kb.xml.*. git-svn-id: https://oai4j-client.svn.sourceforge.net/svnroot/oai4j-client/trunk@13 201c9376-5148-0410-b534-98494c770f31 --- pom.xml | 14 ++++ .../java/se/kb/oai/ore/AggregateBase.java | 53 ++++++++++++ .../se/kb/oai/ore/AggregatedResource.java | 28 +++++++ src/main/java/se/kb/oai/ore/Aggregation.java | 55 +++++++++++++ src/main/java/se/kb/oai/ore/Metadata.java | 33 +++++++- src/main/java/se/kb/oai/ore/ResourceMap.java | 81 +++++++++++++++++++ .../se/kb/oai/ore/ResourceMapFactory.java | 43 ++++++++++ .../se/kb/oai/ore/ResourceMapSerializer.java | 23 ++++++ src/main/java/se/kb/oai/ore/Type.java | 12 ++- src/main/java/se/kb/xml/XMLUtils.java | 25 ++++++ src/main/java/se/kb/xml/XPathWrapper.java | 57 ++++++++++++- 11 files changed, 421 insertions(+), 3 deletions(-) diff --git a/pom.xml b/pom.xml index 5a34169..0f757e2 100644 --- a/pom.xml +++ b/pom.xml @@ -38,6 +38,19 @@ 1.5 + + org.apache.maven.plugins + maven-jar-plugin + 2.2 + + + **/oai/*.class + **/oai/ore/** + **/oai/pmh/** + **/xml/** + + + @@ -51,6 +64,7 @@ http://java.sun.com/javase/6/docs/api/ http://www.dom4j.org/apidocs/ + se.kb.oai.main diff --git a/src/main/java/se/kb/oai/ore/AggregateBase.java b/src/main/java/se/kb/oai/ore/AggregateBase.java index bac3d62..4f8badd 100644 --- a/src/main/java/se/kb/oai/ore/AggregateBase.java +++ b/src/main/java/se/kb/oai/ore/AggregateBase.java @@ -35,36 +35,79 @@ public abstract class AggregateBase { protected List types; protected List metadata; + /** + * Creates an AggregateBase with the specified id. + * + * @param id the id + */ public AggregateBase(URI id) { this.id = id; this.types = new LinkedList(); this.metadata = new LinkedList(); } + /** + * Get the id. + * + * @return the id + */ public URI getId() { return id; } + /** + * Set the id. + * + * @param id the id + */ public void setId(URI id) { this.id = id; } + /** + * Get all types associated with this object. + * + * @return a list of types + */ public List getTypes() { return types; } + /** + * Set the types associated with this object. + * + * @param types a list of types + */ public void setTypes(List types) { this.types = types; } + /** + * Add a Type to this object. + * + * @param type a type + */ public void addType(Type type) { types.add(type); } + /** + * Get a list of all the Metadata for this object. + * + * @return a list with metadata + */ public List getMetadata() { return metadata; } + /** + * Get a list of only the Metadata that matches + * the qualified name for this object. + * + * @param name a qualified name + * + * @return a list with metadata + */ public List getMetadata(QName name) { List list = new LinkedList(); for (Metadata meta : metadata) { @@ -75,10 +118,20 @@ public abstract class AggregateBase { return list; } + /** + * Set the metadata for this object. + * + * @param metadata a list with metadata + */ public void setMetadata(List metadata) { this.metadata = metadata; } + /** + * Add a Metadata to the list of metadata. + * + * @param meta a metadata + */ public void addMetadata(Metadata meta) { metadata.add(meta); } diff --git a/src/main/java/se/kb/oai/ore/AggregatedResource.java b/src/main/java/se/kb/oai/ore/AggregatedResource.java index 635d029..928e545 100644 --- a/src/main/java/se/kb/oai/ore/AggregatedResource.java +++ b/src/main/java/se/kb/oai/ore/AggregatedResource.java @@ -31,17 +31,45 @@ import java.net.URISyntaxException; */ public class AggregatedResource extends AggregateBase { + /** + * Create an AggreagatedResource with the specified id. + * + * @param id the id + * + * @throws URISyntaxException + */ public AggregatedResource(String id) throws URISyntaxException { this(new URI(id)); } + + /** + * Create an AggreagatedResource with the specified id. + * + * @param id the id + */ public AggregatedResource(URI id) { super(id); } + /** + * Get an InputStream for the content held in this + * AggreagatedResource. + * + * @return a stream to the content + * @throws IOException + */ public InputStream getContent() throws IOException { return id.toURL().openStream(); } + + /** + * Get a String containing the content for this + * AggreagatedResource. + * + * @return a stream to the content + * @throws IOException + */ public String getContentAsString() throws IOException { InputStream in = getContent(); ByteArrayOutputStream out = new ByteArrayOutputStream(); diff --git a/src/main/java/se/kb/oai/ore/Aggregation.java b/src/main/java/se/kb/oai/ore/Aggregation.java index c90e361..01d52fd 100644 --- a/src/main/java/se/kb/oai/ore/Aggregation.java +++ b/src/main/java/se/kb/oai/ore/Aggregation.java @@ -33,31 +33,76 @@ public class Aggregation extends AggregateBase { private List resources; + /** + * Create an Aggregation with the specified id. + * + * @param id the id + * + * @throws URISyntaxException + */ public Aggregation(String id) throws URISyntaxException { this(new URI(id)); } + /** + * Create an Aggregation with the specified id. + * + * @param id the id + */ public Aggregation(URI id) { super(id); this.resources = new LinkedList(); } + /** + * Get the number of resources that this Aggregation has. + * + * @return the number of resources + */ public int numberOfResources() { return resources.size(); } + /** + * Get this Aggregations list of AggreagatedResources. + * + * @return a list of resources + */ public List getResources() { return resources; } + /** + * Get the AggreagatedResource at the specified index. + * (There is no guarantee of the ordering of the resources for different + * parsings of the same resource map!) + * + * @param index the index + * + * @return the resource + */ public AggregatedResource getResource(int index) { return resources.get(index); } + /** + * Get the AggreagatedResource with the given id. + * + * @param id the id of the resource + * + * @return the resource + */ public AggregatedResource getResource(String id) throws URISyntaxException { return getResource(new URI(id)); } + /** + * Get the AggreagatedResource with the given id. + * + * @param id the id of the resource + * + * @return the resource, or null if no match + */ public AggregatedResource getResource(URI id) { for (AggregatedResource resource : resources) { if (resource.getId().equals(id)) { @@ -67,10 +112,20 @@ public class Aggregation extends AggregateBase { return null; } + /** + * Set the list of resources. + * + * @param resources the list of resources + */ public void setResources(List resources) { this.resources = resources; } + /** + * Add an AggreagatedResource to this Aggregation. + * + * @param resource a resource + */ public void addResource(AggregatedResource resource) { resources.add(resource); } diff --git a/src/main/java/se/kb/oai/ore/Metadata.java b/src/main/java/se/kb/oai/ore/Metadata.java index 8c6a03f..cacab88 100644 --- a/src/main/java/se/kb/oai/ore/Metadata.java +++ b/src/main/java/se/kb/oai/ore/Metadata.java @@ -21,7 +21,7 @@ import static se.kb.oai.ore.OREConstants.*; import org.dom4j.QName; /** - * Class that represents metadata that can be set for an Aggregation + * Class that represents a metadata element that can be set for an Aggregation * or an AggreagatedResource. Only metadata from the Dublin Core elements * (DC) namespace or the Dublin Core terms (DCTERMS) namespace can be created. * @@ -34,23 +34,54 @@ public class Metadata { private QName qname; private String value; + /** + * Create a Metadata. + * + * @param ns a namespace, can only be DC or DCTERMS + * @param name the name of the metadata element + * @param value the value of the metadata + */ public Metadata(Namespace ns, String name, String value) { this.qname = getName(ns, name); this.value = value; } + /** + * Get the qualified name of this metadata. + * + * @return the name + */ public QName getName() { return qname; } + /** + * Get the value of this metadata. + * + * @return the value + */ public String getValue() { return value; } + /** + * Set the value. + * + * @param value the value + */ public void setValue(String value) { this.value = value; } + /** + * Helper method that creates a qualified name with the given + * namespace and name. + * + * @param ns a namespace, can only be DC or DCTERMS + * @param name the name + * + * @return a qualified name + */ public static QName getName(Namespace ns, String name) { switch (ns) { case DC: diff --git a/src/main/java/se/kb/oai/ore/ResourceMap.java b/src/main/java/se/kb/oai/ore/ResourceMap.java index d24a89a..048fa41 100644 --- a/src/main/java/se/kb/oai/ore/ResourceMap.java +++ b/src/main/java/se/kb/oai/ore/ResourceMap.java @@ -37,59 +37,140 @@ public class ResourceMap { private Date modified; private Aggregation aggregation; + /** + * Create an ResourceMap with the specified id. + * + * @param id the id + * + * @throws URISyntaxException + */ public ResourceMap(String id) throws URISyntaxException { this(new URI(id)); } + /** + * Create an ResourceMap with the specified id. + * + * @param id the id + */ public ResourceMap(URI id) { this.id = id; this.aggregation = new Aggregation(id.resolve("#aggregation")); } + /** + * Get the id. + * + * @return the id + */ public URI getId() { return id; } + /** + * Set the id. + * + * @param id the id + */ public void setId(URI id) { this.id = id; } + /** + * Get the creator of this resource map. + * (Note: NOT the creator of the aggregation or the resources.) + * + * @return the creator + */ public String getCreator() { return creator; } + /** + * Set the creator of this resource map. + * (Note: NOT the creator of the aggregation or the resources.) + * + * @param creator the creator + */ public void setCreator(String creator) { this.creator = creator; } + /** + * Get the rights of this resource map. + * (Note: NOT the rights of the aggregation or the resources.) + * + * @return the rights + */ public String getRights() { return rights; } + /** + * Set the rights of this resource map. + * (Note: NOT the rights of the aggregation or the resources.) + * + * @param rights the rights + */ public void setRights(String rights) { this.rights = rights; } + /** + * Get the creation date of this resource map. + * (Note: NOT the creation date of the aggregation or the resources.) + * + * @return the creation date + */ public Date getCreated() { return created; } + /** + * Set the creation date of this resource map. + * (Note: NOT the creation date of the aggregation or the resources.) + * + * @param created the creation date + */ public void setCreated(Date created) { this.created = created; } + + /** + * Get the modification date of this resource map. + * (Note: NOT the modification date of the aggregation or the resources.) + * + * @return the modification date + */ public Date getModified() { return modified; } + /** + * Set the modification date of this resource map. + * (Note: NOT the modification date of the aggregation or the resources.) + * + * @param modified he modification date + */ public void setModified(Date modified) { this.modified = modified; } + /** + * Get the aggregation that this resource map describes. + * + * @return the aggregation + */ public Aggregation getAggregation() { return aggregation; } + /** + * Set the aggregation that this resource map describes. + * + * @param aggregation the aggregation + */ public void setAggregation(Aggregation aggregation) { this.aggregation = aggregation; } diff --git a/src/main/java/se/kb/oai/ore/ResourceMapFactory.java b/src/main/java/se/kb/oai/ore/ResourceMapFactory.java index 0f4aee8..bbb3ac1 100644 --- a/src/main/java/se/kb/oai/ore/ResourceMapFactory.java +++ b/src/main/java/se/kb/oai/ore/ResourceMapFactory.java @@ -40,13 +40,56 @@ import se.kb.oai.OAIException; */ public interface ResourceMapFactory { + /** + * Create a new ResourceMap with this id. + * + * @param uri the id + * + * @return a new resource map + * @throws URISyntaxException + */ public ResourceMap newResourceMap(String uri) throws URISyntaxException; + /** + * Create a new ResourceMap with this id. + * + * @param uri the id + * + * @return a new resource map + */ public ResourceMap newResourceMap(URI uri); + /** + * Parse the content of the URL and create a ResourceMap + * from it. + * + * @param url a URL + * + * @return a resource map representing the content of the URL + * @throws OAIException + */ public ResourceMap getResourceMap(URL url) throws OAIException; + + /** + * Parse the content of the URL and create a ResourceMap + * from it. + * + * @param url a URL + * + * @return a resource map representing the content of the URL + * @throws OAIException + */ public ResourceMap getResourceMap(String url) throws OAIException; + + /** + * Parse the XML and create a ResourceMap from it. + * + * @param root a XML element + * + * @return a resource map representing the content of the XML + * @throws OAIException + */ public ResourceMap getResourceMap(Element root) throws OAIException; } diff --git a/src/main/java/se/kb/oai/ore/ResourceMapSerializer.java b/src/main/java/se/kb/oai/ore/ResourceMapSerializer.java index 69e3c04..fc01da5 100644 --- a/src/main/java/se/kb/oai/ore/ResourceMapSerializer.java +++ b/src/main/java/se/kb/oai/ore/ResourceMapSerializer.java @@ -36,9 +36,32 @@ import org.dom4j.Element; */ public interface ResourceMapSerializer { + /** + * Serialize the resource map to the given file. + * + * @param file a file + * @param map a resource map + * + * @throws IOException + */ public void serializeToFile(File file, ResourceMap map) throws IOException; + /** + * Serialize the resource map and return it as a String. + * + * @param map a resource map + * + * @return a String with the serialized resource map + * @throws IOException + */ public String serializeToString(ResourceMap map) throws IOException; + /** + * Serialize the resource map into XML. + * + * @param map a resource map + * + * @return an Element containing the result of the serialization + */ public Element serializeToXml(ResourceMap map); } diff --git a/src/main/java/se/kb/oai/ore/Type.java b/src/main/java/se/kb/oai/ore/Type.java index 50b72ea..47c9304 100644 --- a/src/main/java/se/kb/oai/ore/Type.java +++ b/src/main/java/se/kb/oai/ore/Type.java @@ -17,7 +17,7 @@ package se.kb.oai.ore; /** - * Class that are used for typing Aggreagations and + * Class that are used for typing Aggregations and * AggreagatedResources. * * @author Oskar Grenholm, National Library of Sweden @@ -26,10 +26,20 @@ public class Type { private String value; + /** + * Create a typing with this value. + * + * @param value a value + */ public Type(String value) { this.value = value; } + /** + * Get the value. + * + * @return the value + */ public String getValue() { return value; } diff --git a/src/main/java/se/kb/xml/XMLUtils.java b/src/main/java/se/kb/xml/XMLUtils.java index 891eba5..bda7559 100644 --- a/src/main/java/se/kb/xml/XMLUtils.java +++ b/src/main/java/se/kb/xml/XMLUtils.java @@ -25,10 +25,27 @@ import org.dom4j.Element; import org.dom4j.io.OutputFormat; import org.dom4j.io.XMLWriter; +/** + * Utility class that has some static helper methods for handling XML. + * + * @author Oskar Grenholm, National Library of Sweden + */ public class XMLUtils { public static final String ENCODING = "UTF-8"; + /* No need for a constructor. */ + private XMLUtils() {} + + /** + * Writes the XML contained in the Element to the specified + * OutputStream. + * + * @param element the XML element to write + * @param stream the stream to write to + * + * @throws IOException + */ public static void writeXmlTo(Element element, OutputStream stream) throws IOException { OutputStreamWriter writer = new OutputStreamWriter(stream, ENCODING); OutputFormat format = OutputFormat.createPrettyPrint(); @@ -40,6 +57,14 @@ public class XMLUtils { writer.flush(); } + /** + * Converts an Element to a String. + * + * @param xml the XML element to write + * + * @return a String with the XML + * @throws IOException + */ public static String xmlToString(Element xml) throws IOException { ByteArrayOutputStream stream = new ByteArrayOutputStream(); writeXmlTo(xml, stream); diff --git a/src/main/java/se/kb/xml/XPathWrapper.java b/src/main/java/se/kb/xml/XPathWrapper.java index 0ce2668..36ad68a 100644 --- a/src/main/java/se/kb/xml/XPathWrapper.java +++ b/src/main/java/se/kb/xml/XPathWrapper.java @@ -25,41 +25,96 @@ import org.dom4j.Element; import org.dom4j.Node; import org.dom4j.XPath; +/** + * Helper class that eases the job of handling XPath queries and + * getting the different results. It wraps a {@link org.dom4j.Node} + * and then performs the XPath queries on that. + * + * @author Oskar Grenholm, National Library of Sweden + */ public class XPathWrapper { private Node node; private Map namespaces; + /** + * Wraps a Node for easier XPath handling. + * + * @param node the Node to wrap + */ public XPathWrapper(Node node) { this(node, new HashMap()); } + /** + * Creates a XPathWrapper that should be aware of all + * the namespaces in the Map when handling XPath queries. + * + * @param node the Node to wrap + * @param namespaces the namespaces + */ public XPathWrapper(Node node, Map namespaces) { this.node = node; this.namespaces = namespaces; } + /** + * Adds a namespace that the wrapper should be aware of when performing + * XPath queries. + * + * @param prefix the prefix of the namespace + * @param uri the uri of the namespace + */ public void addNamespace(String prefix, String uri) { namespaces.put(prefix, uri); } + /** + * Selects a single node that matches the given XPath. + * + * @param xpathExpression the xpath + * + * @return a single Node or null if no match + */ public Node selectSingleNode(String xpathExpression) { XPath xpath = createXPath(xpathExpression); return xpath.selectSingleNode(node); } + /** + * Selects all Nodes that matches the given XPath. + * + * @param xpathExpression the xpath + * + * @return a list of nodes (can be empty if no matches) + */ @SuppressWarnings("unchecked") public List selectNodes(String xpathExpression) { XPath xpath = createXPath(xpathExpression); return xpath.selectNodes(node); } + /** + * Selects a single result that matches the given XPath and + * then casts it into a Element. + * + * @param xpathExpression the xpath + * + * @return a single Element or null if no match + */ public Element selectSingleElement(String xpathExpression) { return (Element) selectSingleNode(xpathExpression); } + /** + * Selects the value of the given XPath. + * + * @param xpathExpression the xpath + * + * @return the value or null if no match + */ public String valueOf(String xpathExpression) { - XPath xpath =createXPath(xpathExpression); + XPath xpath = createXPath(xpathExpression); return xpath.valueOf(node); }