You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@poi.apache.org by ki...@apache.org on 2018/08/19 22:01:19 UTC
svn commit: r1838403 - in /xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans:
BindingConfig.java CDataBookmark.java DelegateXmlObject.java Filer.java
XmlCursor.java XmlObject.java
Author: kiwiwings
Date: Sun Aug 19 22:01:19 2018
New Revision: 1838403
URL: http://svn.apache.org/viewvc?rev=1838403&view=rev
Log:
Javadoc fixes
Modified:
xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans/BindingConfig.java
xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans/CDataBookmark.java
xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans/DelegateXmlObject.java
xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans/Filer.java
xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans/XmlCursor.java
xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans/XmlObject.java
Modified: xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans/BindingConfig.java
URL: http://svn.apache.org/viewvc/xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans/BindingConfig.java?rev=1838403&r1=1838402&r2=1838403&view=diff
==============================================================================
--- xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans/BindingConfig.java (original)
+++ xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans/BindingConfig.java Sun Aug 19 22:01:19 2018
@@ -35,64 +35,71 @@ public class BindingConfig
public static final int QNAME_ACCESSOR_ATTRIBUTE = 4;
/**
- * Get the package name for a namespace or null.
+ * @param uri the namespace uri
+ * @return the package name for a namespace or null.
*/
public String lookupPackageForNamespace(String uri) { return null; }
/**
- * Get the prefix applied to each java name for a namespace or null.
+ * @param uri the namespace uri
+ * @return the prefix applied to each java name for a namespace or null.
*/
public String lookupPrefixForNamespace(String uri) { return null; }
/**
- * Get the suffix applied to each java name for a namespace or null.
+ * @param uri the namespace uri
+ * @return Get the suffix applied to each java name for a namespace or null.
*/
public String lookupSuffixForNamespace(String uri) { return null; }
/**
- * Get the java name for a QName or null.
+ * @param qname the qname of the java name
+ * @return the java name for a QName or null.
* @deprecated replaced with {@link #lookupJavanameForQName(QName, int)}
*/
public String lookupJavanameForQName(QName qname) { return null; }
/**
- * Get the java name for a QName of a specific component kind, or null.
- * @see #QNAME_TYPE
- * @see #QNAME_TYPE_DOCUMENT
- * @see #QNAME_METHOD_ELEMENT
- * @see #QNAME_METHOD_ATTRIBUTE
+ * @param qname the qname of the java name
+ * @param kind the type of the qname, which one of {@link #QNAME_TYPE}, {@link #QNAME_DOCUMENT_TYPE},
+ * {@link #QNAME_ACCESSOR_ELEMENT}, {@link #QNAME_ACCESSOR_ATTRIBUTE}
+ *
+ * @return Get the java name for a QName of a specific component kind, or null.
*/
public String lookupJavanameForQName(QName qname, int kind) { return null; }
/**
- * Returns all configured InterfaceExtensions or an empty array.
+ * @return all configured InterfaceExtensions or an empty array.
*/
public InterfaceExtension[] getInterfaceExtensions() { return EMPTY_INTERFACE_EXT_ARRAY; }
/**
- * Returns all InterfaceExtensions defined for the fully qualified java
+ * @param fullJavaName the fully qualified java type name
+ * @return all InterfaceExtensions defined for the fully qualified java
* type generated from schema compilation or an empty array.
*/
public InterfaceExtension[] getInterfaceExtensions(String fullJavaName) { return EMPTY_INTERFACE_EXT_ARRAY; }
/**
- * Returns all configued PrePostExtensions or an empty array.
+ * @return all configued PrePostExtensions or an empty array.
*/
public PrePostExtension[] getPrePostExtensions() { return EMPTY_PREPOST_EXT_ARRAY; }
/**
- * Returns the PrePostExtension defined for the fully qualified java
+ * @param fullJavaName the fully qualified java type name
+ * @return the PrePostExtension defined for the fully qualified java
* type generated from schema compilation or null.
*/
public PrePostExtension getPrePostExtension(String fullJavaName) { return null; }
/**
- * Returns all defined user types.
+ * @return all defined user types.
*/
public UserType[] getUserTypes() { return EMPTY_USER_TYPE_ARRY; }
/**
- * Returns a user defined Java type for a given QName.
+ * @param qname the qname of the user type
+ * @return a user defined Java type for a given QName.
*/
public UserType lookupUserTypeForQName(QName qname) { return null; }
Modified: xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans/CDataBookmark.java
URL: http://svn.apache.org/viewvc/xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans/CDataBookmark.java?rev=1838403&r1=1838402&r2=1838403&view=diff
==============================================================================
--- xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans/CDataBookmark.java (original)
+++ xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans/CDataBookmark.java Sun Aug 19 22:01:19 2018
@@ -15,30 +15,30 @@
package org.apache.xmlbeans;
/**
- * Represents a CDATA bookmark.
+ * Represents a CDATA bookmark.<p>
*
- * <p>When XmlOption UseCDataBookmarks is setted on parse methods,
+ * When XmlOption UseCDataBookmarks is setted on parse methods,
* the loader will set these CDataBookmarks in the store on the respective
- * TEXT fields that were represented as CDATA.</p>
+ * TEXT fields that were represented as CDATA.<p>
*
- * <p>Users can modify the 'look' of TEXT fields, by annotating them with
- * this bookmark, or remove the bookmark.</p>
+ * Users can modify the 'look' of TEXT fields, by annotating them with
+ * this bookmark, or remove the bookmark.<p>
*
- * <p>Additionaly if setted on save methods, the output will look for these
+ * Additionaly if setted on save methods, the output will look for these
* bookmarks and will output the text as CDATA.
* Note: The SaveCDataEntityCountThreshold and SaveCDataLengthThreshold
- * options and their default values still apply.</p>
+ * options and their default values still apply.<p>
*
- * <p>Note: Due to the store representation, a CDATA will not be recognized
+ * Note: Due to the store representation, a CDATA will not be recognized
* if it is imediately after non CDATA text and all text following it will
- * be considered CDATA.<br/>
+ * be considered CDATA.<br>
* Example:<br>
* <pre>
- * <a><![CDATA[cdata text]]></a> - is considered as: <a><![CDATA[cdata text]]></a>
- * <b><![CDATA[cdata text]]> regular text</b> - is considered as: <b><![CDATA[cdata text regular text]]></b>
- * <c>text <![CDATA[cdata text]]></c> - is considered as: <c>text cdata text</c>
+ * <a><![CDATA[cdata text]]></a> - is considered as: <a><![CDATA[cdata text]]></a>
+ * <b><![CDATA[cdata text]]> regular text</b> - is considered as: <b><![CDATA[cdata text regular text]]></b>
+ * <c>text <![CDATA[cdata text]]></c> - is considered as: <c>text cdata text</c>
* </pre>
- * </p>
+ *
* @see XmlOptions#setUseCDataBookmarks()
* @see org.apache.xmlbeans.XmlObject.Factory#parse(String, XmlOptions)
* @see org.apache.xmlbeans.XmlObject#save(java.io.OutputStream, XmlOptions)
Modified: xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans/DelegateXmlObject.java
URL: http://svn.apache.org/viewvc/xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans/DelegateXmlObject.java?rev=1838403&r1=1838402&r2=1838403&view=diff
==============================================================================
--- xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans/DelegateXmlObject.java (original)
+++ xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans/DelegateXmlObject.java Sun Aug 19 22:01:19 2018
@@ -23,6 +23,8 @@ public interface DelegateXmlObject
/**
* This method is called to obtain the underlying XmlObject.
* Implement this method to supply or compute the wrapped object.
+ *
+ * @return the underlying XmlObject
*/
XmlObject underlyingXmlObject();
}
Modified: xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans/Filer.java
URL: http://svn.apache.org/viewvc/xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans/Filer.java?rev=1838403&r1=1838402&r2=1838403&view=diff
==============================================================================
--- xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans/Filer.java (original)
+++ xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans/Filer.java Sun Aug 19 22:01:19 2018
@@ -30,7 +30,8 @@ public interface Filer
*
* @param typename fully qualified type name
* @return a stream to write the type to
- * @throws IOException
+ *
+ * @throws IOException when the file can't be created
*/
public OutputStream createBinaryFile(String typename) throws IOException;
@@ -39,7 +40,8 @@ public interface Filer
*
* @param typename fully qualified type name
* @return a stream to write the type to
- * @throws IOException
+ *
+ * @throws IOException when the file can't be created
*/
public Writer createSourceFile(String typename) throws IOException;
Modified: xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans/XmlCursor.java
URL: http://svn.apache.org/viewvc/xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans/XmlCursor.java?rev=1838403&r1=1838402&r2=1838403&view=diff
==============================================================================
--- xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans/XmlCursor.java (original)
+++ xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans/XmlCursor.java Sun Aug 19 22:01:19 2018
@@ -1336,6 +1336,8 @@ public interface XmlCursor extends XmlTo
* on the bookmark. Subsequent navigations to bookmark
* positions should attempt to reuse the last cursor to
* improve performace.
+ *
+ * @return the new cursor
*/
public final XmlCursor createCursor ( )
{
@@ -1343,7 +1345,8 @@ public interface XmlCursor extends XmlTo
}
/**
- * Moves the given cursor to this bookmark, and returns it.
+ * @param c the cursor to be moved
+ * @return the given cursor moved to this bookmark
*/
public final XmlCursor toBookmark ( XmlCursor c )
{
@@ -1356,6 +1359,8 @@ public interface XmlCursor extends XmlTo
* same instance document will not interfere with eachother.
* One can, however, override getKey() to use a key other than
* the class.
+ *
+ * @return default key for bookmarks
*/
public Object getKey ( )
{
Modified: xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans/XmlObject.java
URL: http://svn.apache.org/viewvc/xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans/XmlObject.java?rev=1838403&r1=1838402&r2=1838403&view=diff
==============================================================================
--- xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans/XmlObject.java (original)
+++ xmlbeans/trunk/src/xmlpublic/org/apache/xmlbeans/XmlObject.java Sun Aug 19 22:01:19 2018
@@ -139,22 +139,22 @@ public interface XmlObject extends XmlTo
public static final SchemaType type = XmlBeans.getBuiltinTypeSystem().typeForHandle("_BI_anyType");
/**
- * The schema type for this instance. This is a permanent,
+ * @return The schema type for this instance. This is a permanent,
* unchanging property of the instance.
*/
SchemaType schemaType();
/**
- * Returns true if the contents of this object are valid
- * accoring to schemaType().
- * <p>
* Does a deep validation of the entire subtree under the
* object, but does not validate the parents or siblings
* of the object if the object is in the interior of an xml
* tree.
+ *
+ * @return true if the contents of this object are valid
+ * accoring to schemaType().
*/
boolean validate();
-
+
/**
* <p>Just like validate(), but with options.</p>
* <p>If you wish to collect error messages and locations while validating,
@@ -175,7 +175,7 @@ public interface XmlObject extends XmlTo
* // printing contained messages.
* if (!isValid)
* {
- * for (int i = 0; i < errorList.size(); i++)
+ * for (int i = 0; i < errorList.size(); i++)
* {
* XmlError error = (XmlError)errorList.get(i);
*
@@ -189,35 +189,44 @@ public interface XmlObject extends XmlTo
*
* @param options An object that implements the {@link java.util.Collection
* Collection} interface.
+ *
+ * @return true if the contents of this object are valid
+ * accoring to schemaType().
*/
boolean validate(XmlOptions options);
/**
* Selects a path. Path can be a string or precompiled path String.
* <p>
+ *
* The path must be a relative path, where "." represents the
* element or attribute containg this XmlObject, and it must select
* only other elements or attributes. If a non-element or non-attribute
* is selected, an unchecked exception is thrown.
* <p>
+ *
* The array that is returned contains all the selected
* XmlObjects, within the same document, listed in document
* order. The actual array type of the result is inferred
* from the closest common base type of selected results.
* <p>
+ *
* Here is an example of usage. Suppose we have a global
* element definition for "owner" whose type is "person":
+ *
* <pre>
- * <schema targetNamespace="http://openuri.org/sample">
- * <element name="owner" type="person"/>
- * <complexType name="person">
+ * <schema targetNamespace="http://openuri.org/sample">
+ * <element name="owner" type="person"/>
+ * <complexType name="person">
* [...]
- * </complexType>
- * </schema>
+ * </complexType>
+ * </schema>
* </pre>
+ *
* and suppose "owner" tags can be scattered throughout the
* document. Then we can write the following code to find
* them all:
+ *
* <pre>
* import org.openuri.sample.Person;
* import org.apache.xmlbeans.*;
@@ -228,16 +237,24 @@ public interface XmlObject extends XmlTo
* "declare namespace s='http://www.openuri.org/sample' " +
* ".//s:owner");
* </pre>
+ *
* Notice the way in which namespace declarations are done in XPath 2.0.
* Since XPath can only navigate within an XML document - it cannot
* construct new XML - the resulting XmlObjects all reside in
* the same XML document as this XmlObject itself.
+ *
+ * @param path the xpath
+ * @return an array of all selected XmlObjects
*/
XmlObject[] selectPath ( String path );
/**
* Selects a path, applying options.
- *
+ *
+ * @param path the xpath
+ * @param options the options used to execute the xpath
+ * @return an array of all selected XmlObjects
+ *
* @see #selectPath(String)
*/
XmlObject[] selectPath ( String path, XmlOptions options );
@@ -253,6 +270,10 @@ public interface XmlObject extends XmlTo
* <p>
* Syntax and usage is otherwise similar to selectPath.
* <p>
+ *
+ * @param query The XQuery expression
+ * @return an array of all selected XmlObjects
+ *
* @see #selectPath(String)
*/
XmlObject[] execQuery ( String query );
@@ -306,7 +327,9 @@ public interface XmlObject extends XmlTo
*
* @param query The XQuery expression.
* @param options Options as described.
- *
+ *
+ * @return an array of all selected XmlObjects
+ *
* @see #execQuery(String)
*/
XmlObject[] execQuery ( String query, XmlOptions options );
@@ -334,6 +357,8 @@ public interface XmlObject extends XmlTo
*
* If a type change is done on the interior of an Xml
* tree, then xsi:type attributes are updated as needed.
+ *
+ * @return a new XmlObject instance whose schemaType is the new type
*/
XmlObject changeType(SchemaType newType);
@@ -357,13 +382,21 @@ public interface XmlObject extends XmlTo
* invalidated and should not be used. (They will return
* XmlValueDisconnectedException if you try to use them.)
* If necessary, xsi:type attributes are updated.
+ *
+ * @param newName the new name
+ * @param newType the new type
+ *
+ * @return an XmlObject instance whose schemaType is the
+ * new type and container name is the new name
*/
XmlObject substitute(QName newName, SchemaType newType);
/**
- * True if the value is nil. Note that in order to be nil,
+ * Note that in order to be nil,
* the value must be in an element, and the element containing
* the value must be marked as nillable in the schema.
+ *
+ * @return true if the value is nil.
*/
boolean isNil();
@@ -375,8 +408,6 @@ public interface XmlObject extends XmlTo
/**
- * Returns an XML string for this XML object.
- * <p>
* The string is pretty-printed. If you want a non-pretty-printed
* string, or if you want to control options precisely, use the
* xmlText() methods.
@@ -387,14 +418,17 @@ public interface XmlObject extends XmlTo
* and we will produce a string that starts with an <code><xml-fragment></code> tag.
* The XmlOptions.setSaveOuter() option on xmlText can be used to produce
* the actual element name above the object if you wish.
+ *
+ * @return a XML string for this XML object.
*/
String toString();
/**
- * True if the value is an immutable value. Immutable values do not
- * have a position in a tree; rather, they are stand-alone simple type
- * values. If the object is immutable, the equals() methods tests for
- * value equality, and the object can be used as the key for a hash.
+ * Immutable values do not have a position in a tree; rather, they are
+ * stand-alone simple type values. If the object is immutable, the equals()
+ * methods tests for value equality, and the object can be used as the key for a hash.
+ *
+ * @return true if the value is an immutable value.
*/
boolean isImmutable();
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@poi.apache.org
For additional commands, e-mail: dev-help@poi.apache.org