From: Ray Lee Date: Tue, 2 Aug 2016 20:52:22 +0000 (-0700) Subject: DRYD-23: Improve javadoc formatting. X-Git-Url: https://git.aero2k.de/?a=commitdiff_plain;h=cfca1ec2e3436c3e30277af3858b242cb1db772f;p=tmp%2Fjakarta-migration.git DRYD-23: Improve javadoc formatting. --- diff --git a/services/common/src/main/java/org/collectionspace/services/common/xmljson/JsonField.java b/services/common/src/main/java/org/collectionspace/services/common/xmljson/JsonField.java index 5f3ebf421..9d71f2f10 100644 --- a/services/common/src/main/java/org/collectionspace/services/common/xmljson/JsonField.java +++ b/services/common/src/main/java/org/collectionspace/services/common/xmljson/JsonField.java @@ -1,12 +1,12 @@ package org.collectionspace.services.common.xmljson; /** - * A lightweight representation of a JSON field. Instances are created + *

A lightweight representation of a JSON field. Instances are created * by JsonToXmlStreamConverter in the course of parsing JSON, in order - * to track the current state. + * to track the current state.

* - * Each JSON field has a name and a type, which is either scalar, array, - * or object. + *

Each JSON field has a name and a type, which is either scalar, array, + * or object.

*/ public class JsonField { private String name; diff --git a/services/common/src/main/java/org/collectionspace/services/common/xmljson/JsonToXmlFilter.java b/services/common/src/main/java/org/collectionspace/services/common/xmljson/JsonToXmlFilter.java index e4c8efca2..8007f3ad0 100644 --- a/services/common/src/main/java/org/collectionspace/services/common/xmljson/JsonToXmlFilter.java +++ b/services/common/src/main/java/org/collectionspace/services/common/xmljson/JsonToXmlFilter.java @@ -18,7 +18,15 @@ import javax.xml.stream.XMLStreamException; import org.apache.commons.io.output.ByteArrayOutputStream; /** - * A filter that translates JSON to XML. + *

A filter that translates JSON requests to XML.

+ * + *

This filter only has an effect if the content of the request (determined from + * the Content-type header) is JSON. If the content is JSON, the request is + * wrapped.

+ * + *

The request wrapper changes the Content-type header to XML, and provides an + * input stream containing an XML translation of the original JSON request + * content.

*/ public class JsonToXmlFilter implements Filter { @@ -51,7 +59,8 @@ public class JsonToXmlFilter implements Filter { } /** - * A request wrapper that . + * A request wrapper that has a content type of XML, and replaces the + * wrapped input stream with an XML translation. */ public class RequestWrapper extends HttpServletRequestWrapper { public RequestWrapper(HttpServletRequest request) { @@ -74,14 +83,32 @@ public class JsonToXmlFilter implements Filter { throw new IOException("error converting JSON stream to XML", e); } - final InputStream xmlInput = out.toInputStream(); + return new InputStreamWrapper(out.toInputStream()); + } + } + + /** + * A ServletInputStream that wraps another input stream. + */ + public class InputStreamWrapper extends ServletInputStream { - return new ServletInputStream() { - @Override - public int read() throws IOException { - return xmlInput.read(); - } - }; + /** + * The wrapped input stream. + */ + private InputStream in; + + /** + * Creates an InputStreamWrapper that wraps a given input stream. + * + * @param in the input stream to wrap + */ + public InputStreamWrapper(InputStream in) { + this.in = in; + } + + @Override + public int read() throws IOException { + return in.read(); } } } diff --git a/services/common/src/main/java/org/collectionspace/services/common/xmljson/JsonToXmlStreamConverter.java b/services/common/src/main/java/org/collectionspace/services/common/xmljson/JsonToXmlStreamConverter.java index bda3a6f1d..0a4c92438 100644 --- a/services/common/src/main/java/org/collectionspace/services/common/xmljson/JsonToXmlStreamConverter.java +++ b/services/common/src/main/java/org/collectionspace/services/common/xmljson/JsonToXmlStreamConverter.java @@ -17,13 +17,14 @@ import com.fasterxml.jackson.core.JsonParser; import com.fasterxml.jackson.core.JsonToken; /** - * Converts a CSpace JSON payload to an XML payload. + *

Converts a CSpace JSON payload to an XML payload.

* - * This class is not intended to serve as a general purpose JSON to XML + *

This class is not intended to serve as a general purpose JSON to XML * translator. It is instead a lightweight processor tuned for the kinds * of JSON generated by CSpace, and the particular transformations needed - * to generate XML for CSpace. + * to generate XML for CSpace.

* + *

* The conversion is performed as follows: *

+ *

* - * This implementation is schema-unaware. It operates by examining only the input - * document, without utilizing any XML schema information. + *

This implementation is schema-unaware. It operates by examining only the input + * document, without utilizing any XML schema information.

* - * Example: + *

Example:

* + *

* JSON * 

  * {
@@ -80,43 +83,46 @@ import com.fasterxml.jackson.core.JsonToken;
  *   }
  * }
  *
- * + *

+ * + *

* XML * 

- * 
- *   
- *     2016.1.1
- *     
- *       
- *         
- *         
- *         Object name
- *         
- *         
- *         
- *         
- *       
- *       
- *         
- *         
- *         Another name
- *         
- *         
- *         
- *         
- *       
- *     
- *     
- *       Some comment text
- *       Another comment
- *     
- *   
- * 
+ * <document name="collectionobjects">
+ *   <ns2:collectionobjects_common xmlns:ns2="http://collectionspace.org/services/collectionobject" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+ *     <objectNumber>2016.1.1</objectNumber>
+ *     <objectNameList>
+ *       <objectNameGroup>
+ *         <objectNameCurrency/>
+ *         <objectNameLanguage/>
+ *         <objectName>Object name</objectName>
+ *         <objectNameSystem/>
+ *         <objectNameType/>
+ *         <objectNameNote/>
+ *         <objectNameLevel/>
+ *       </objectNameGroup>
+ *       <objectNameGroup>
+ *         <objectNameCurrency/>
+ *         <objectNameLanguage/>
+ *         <objectName>Another name</objectName>
+ *         <objectNameSystem/>
+ *         <objectNameType/>
+ *         <objectNameNote/>
+ *         <objectNameLevel/>
+ *       </objectNameGroup>
+ *     </objectNameList>
+ *     <comments>
+ *       <comment>Some comment text</comment>
+ *       <comment>Another comment</comment>
+ *     </comments>
+ *   </ns2:collectionobjects_common>
+ * </document>
  *
+ *

* - * This implementation uses a streaming JSON parser and a streaming + *

This implementation uses a streaming JSON parser and a streaming * XML writer to do a direct stream-to-stream conversion, without - * building a complete in-memory representation of the document. + * building a complete in-memory representation of the document.

*/ public class JsonToXmlStreamConverter { diff --git a/services/common/src/main/java/org/collectionspace/services/common/xmljson/XmlNode.java b/services/common/src/main/java/org/collectionspace/services/common/xmljson/XmlNode.java index 99145aabd..37b3d3937 100644 --- a/services/common/src/main/java/org/collectionspace/services/common/xmljson/XmlNode.java +++ b/services/common/src/main/java/org/collectionspace/services/common/xmljson/XmlNode.java @@ -12,15 +12,15 @@ import org.apache.commons.lang3.StringUtils; import com.fasterxml.jackson.annotation.JsonValue; /** - * A lightweight representation of an XML node. Instances are created + *

A lightweight representation of an XML node. Instances are created * by XmlToJsonStreamConverter in the course of parsing XML. This class * differs from a DOM node in that it is intended to contain just the * information needed to generate JSON for CSpace, in a structure that - * is optimized for doing that generation. + * is optimized for doing that generation.

* - * Each XML node has a name, and optionally namespaces and attributes. + *

Each XML node has a name, and optionally namespaces and attributes. * The node may contain either text or child nodes (not both, as CSpace - * XML is assumed not to contain mixed-content elements). + * XML is assumed not to contain mixed-content elements).

*/ public class XmlNode { /** @@ -78,14 +78,14 @@ public class XmlNode { } /** - * Gets the value of the node. If this is a text node, the + *

Gets the value of the node. If this is a text node, the * value is a String. Otherwise it's a map of the node's * namespaces, attributes, and children, via - * getCombinedMap(). + * getCombinedMap().

* - * Note that namespaces and attributes are not returned + *

Note that namespaces and attributes are not returned * as part of a text node's value. It is assumed that text - * nodes do not have namespace declarations or attributes. + * nodes do not have namespace declarations or attributes.

* * @return the node's value */ @@ -299,14 +299,14 @@ public class XmlNode { } /** - * Adds a child node to this node. + *

Adds a child node to this node.

* - * If the node contains any text content, the text content + *

If the node contains any text content, the text content * is removed, and text content is disallowed from being added - * in the future. + * in the future.

* - * If the node to be added contains no content, and - * isDiscardEmptyChildren() is true, the node is not added. + *

If the node to be added contains no content, and + * isDiscardEmptyChildren() is true, the node is not added.

* * @param node the node to add as a child */ diff --git a/services/common/src/main/java/org/collectionspace/services/common/xmljson/XmlToJsonFilter.java b/services/common/src/main/java/org/collectionspace/services/common/xmljson/XmlToJsonFilter.java index 87a221b9d..843e29722 100644 --- a/services/common/src/main/java/org/collectionspace/services/common/xmljson/XmlToJsonFilter.java +++ b/services/common/src/main/java/org/collectionspace/services/common/xmljson/XmlToJsonFilter.java @@ -28,25 +28,25 @@ import org.apache.commons.io.IOUtils; import org.apache.commons.io.output.ByteArrayOutputStream; /** - * A filter that translates XML responses to JSON. + *

A filter that translates XML responses to JSON.

* - * This filter only has an effect if the preferred content type of the response + *

This filter only has an effect if the preferred content type of the response * (determined from the Accept header) is JSON. If JSON is preferred, both the - * request and response are wrapped. + * request and response are wrapped.

* - * The request wrapper modifies the Accept header, ensuring that XML is accepted + *

The request wrapper modifies the Accept header, ensuring that XML is accepted * in addition to (but at a lower quality factor than) JSON. This handles the * case where the original request only accepts JSON. In that case, XML should * also be accepted, so that the XML response may be translated to JSON on the - * way back. + * way back.

* - * The response wrapper provides a buffered output stream, so that XML output + *

The response wrapper provides a buffered output stream, so that XML output * is captured before being sent over the network. If the content type of the * response is XML, the content type is changed to JSON, the content of the * buffer is translated to JSON, and the JSON is written to the original output * stream. If the content type of the response is not XML, the content type is * not changed, and the content of the buffer is written to the original - * output stream unchanged. + * output stream unchanged.

*/ public class XmlToJsonFilter implements Filter { diff --git a/services/common/src/main/java/org/collectionspace/services/common/xmljson/XmlToJsonStreamConverter.java b/services/common/src/main/java/org/collectionspace/services/common/xmljson/XmlToJsonStreamConverter.java index f7add54f4..99ddc50ad 100644 --- a/services/common/src/main/java/org/collectionspace/services/common/xmljson/XmlToJsonStreamConverter.java +++ b/services/common/src/main/java/org/collectionspace/services/common/xmljson/XmlToJsonStreamConverter.java @@ -21,14 +21,15 @@ import com.fasterxml.jackson.databind.JsonMappingException; import com.fasterxml.jackson.databind.ObjectMapper; /** - * Converts a CSpace XML payload to a JSON payload. + *

Converts a CSpace XML payload to a JSON payload.

* - * This class is not intended to serve as a general purpose XML to JSON + *

This class is not intended to serve as a general purpose XML to JSON * translator. It is instead a lightweight processor tuned for the kinds * of XML generated by CSpace, and the particular transformations needed * to generate JSON for CSpace. The XML input is expected to conform to - * conventions (described below) of CSpace XML payloads. + * conventions (described below) of CSpace XML payloads.

* + *

* The conversion is performed as follows: *

+ *

* + *

* This implementation is schema-unaware. It operates by examining only the input * document, without utilizing any XML schema information. This allows for speed * and simplicity, but has some consequences: @@ -54,46 +57,50 @@ import com.fasterxml.jackson.databind.ObjectMapper; * necessary to read the entire XML document into memory first, instead of * doing a direct stream-to-stream conversion. * - * - * Example: + *

+ * + *

Example:

* + *

* XML * 

- * 
- *   
- *     admin@core.collectionspace.org
- *     2016-07-27T04:31:38.290Z
- *   
- *   
- *     2016.1.1
- *     
- *       
- *         
- *         
- *         Object name
- *         
- *         
- *         
- *         
- *       
- *       
- *         
- *         
- *         Another name
- *         
- *         
- *         
- *         
- *       
- *     
- *     
- *       Some comment text
- *       Another comment
- *     
- *   
- * 
+ * <document name="collectionobjects">
+ *   <ns2:collectionspace_core xmlns:ns2="http://collectionspace.org/collectionspace_core/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+ *     <createdBy>admin@core.collectionspace.org</createdBy>
+ *     <createdAt>2016-07-27T04:31:38.290Z</createdAt>
+ *   </ns2:collectionspace_core>
+ *   <ns2:collectionobjects_common xmlns:ns2="http://collectionspace.org/services/collectionobject" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+ *     <objectNumber>2016.1.1</objectNumber>
+ *     <objectNameList>
+ *       <objectNameGroup>
+ *         <objectNameCurrency/>
+ *         <objectNameLanguage/>
+ *         <objectName>Object name</objectName>
+ *         <objectNameSystem/>
+ *         <objectNameType/>
+ *         <objectNameNote/>
+ *         <objectNameLevel/>
+ *       </objectNameGroup>
+ *       <objectNameGroup>
+ *         <objectNameCurrency/>
+ *         <objectNameLanguage/>
+ *         <objectName>Another name</objectName>
+ *         <objectNameSystem/>
+ *         <objectNameType/>
+ *         <objectNameNote/>
+ *         <objectNameLevel/>
+ *       </objectNameGroup>
+ *     </objectNameList>
+ *     <comments>
+ *       <comment>Some comment text</comment>
+ *       <comment>Another comment</comment>
+ *     </comments>
+ *   </ns2:collectionobjects_common>
+ * </document>
  *
+ *

* + *

* JSON * 

  * {
@@ -141,7 +148,9 @@ import com.fasterxml.jackson.databind.ObjectMapper;
  *   }
  * }
  *
+ *

* + *

* The conversion algorithm assumes that the input XML adheres to the following * conventions: * @@ -154,18 +163,18 @@ import com.fasterxml.jackson.databind.ObjectMapper; * only text, they are discarded. *

  • The XML does not contain sequences of identically-named elements that are * interrupted by other elements; or if it does, those interruptions are not - * important. For example, the parent node below contains a list of item - * elements, interrupted by an other element: + * important. For example, the parent node below contains a list of item + * elements, interrupted by an other element: * * 
    - *       
- *         a
- *         b
- *         c
- *         uh oh
- *         d
- *         e
- *       
+ *       <parent>
+ *         <item>a</item>
+ *         <item>b</item>
+ *         <item>c</item>
+ *         <other>uh oh</other>
+ *         <item>d</item>
+ *         <item>e</item>
+ *       </parent>
  *
    * * This is translated to: @@ -183,20 +192,21 @@ import com.fasterxml.jackson.databind.ObjectMapper; * } * * - * All of the item children of parent are converted into a single - * list, so the placement of the other element is not retained in + * All of the item children of parent are converted into a single + * list, so the placement of the other element is not retained in * JSON. *
    • * + *

    * - * This implementation uses a StAX parser to generate a lightweight + *

    This implementation uses a StAX parser to generate a lightweight * representation of the input XML document in memory, performs the * necessary transformations, and outputs a JSON rendering of the * transformed document. A direct stream-to-stream conversion is * not possible because of the need to collect identically-named * XML elements for output as a JSON array; for any element, all children * must be known before JSON for that element may be written to the - * output stream. + * output stream.

    */ public class XmlToJsonStreamConverter { /**