svn commit: r947642 - in /webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/ext/stax: ./ datahandler/

[ve...@apache.org]

Author: veithen
Date: Mon May 24 13:45:01 2010
New Revision: 947642

URL: http://svn.apache.org/viewvc?rev=947642&view=rev
Log:
Improved the Javadoc of org.apache.axiom.ext.stax and its subpackages.

Added:
    webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/ext/stax/package.html
Modified:
    webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/ext/stax/CharacterDataReader.java
    webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/ext/stax/datahandler/DataHandlerReader.java
    webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/ext/stax/datahandler/DataHandlerWriter.java
    webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/ext/stax/datahandler/package.html

Modified: webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/ext/stax/CharacterDataReader.java
URL: http://svn.apache.org/viewvc/webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/ext/stax/CharacterDataReader.java?rev=947642&r1=947641&r2=947642&view=diff
==============================================================================
--- webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/ext/stax/CharacterDataReader.java (original)
+++ webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/ext/stax/CharacterDataReader.java Mon May 24 13:45:01 2010
@@ -28,6 +28,11 @@ import javax.xml.stream.XMLStreamExcepti
  * Optional interface implemented by {@link javax.xml.stream.XMLStreamReader}
  * implementations that support writing character data directly to a
  * {@link Writer}.
+ * <p>
+ * All the requirements outlined in {@link org.apache.axiom.ext.stax} apply to
+ * this extension interface. In particular, to get a reference to the extension,
+ * the consumer MUST call {@link javax.xml.stream.XMLStreamReader#getProperty(String)}
+ * with {@link #PROPERTY} as the property name.
  */
 public interface CharacterDataReader {
     /**

Modified: webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/ext/stax/datahandler/DataHandlerReader.java
URL: http://svn.apache.org/viewvc/webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/ext/stax/datahandler/DataHandlerReader.java?rev=947642&r1=947641&r2=947642&view=diff
==============================================================================
--- webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/ext/stax/datahandler/DataHandlerReader.java (original)
+++ webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/ext/stax/datahandler/DataHandlerReader.java Mon May 24 13:45:01 2010
@@ -26,9 +26,10 @@ import javax.xml.stream.XMLStreamExcepti
  * Extension interface for {@link javax.xml.stream.XMLStreamReader} implementations that expose
  * base64 encoded binary content as {@link DataHandler} objects.
  * <p>
- * A consumer MUST use {@link javax.xml.stream.XMLStreamReader#getProperty(String)} with the property
- * name defined by {@link #PROPERTY} to get a reference to this extension interface. See
- * the package Javadoc for additional requirements.
+ * All the requirements specified in {@link org.apache.axiom.ext.stax} apply to
+ * this extension interface. In particular,
+ * a consumer MUST use {@link javax.xml.stream.XMLStreamReader#getProperty(String)} with the property
+ * name defined by {@link #PROPERTY} to get a reference to this extension interface.
  * <p>
  * If the {@link javax.xml.stream.XMLStreamReader} wishes to expose base64 encoded content using
  * this extension interface, it MUST do so using a single

Modified: webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/ext/stax/datahandler/DataHandlerWriter.java
URL: http://svn.apache.org/viewvc/webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/ext/stax/datahandler/DataHandlerWriter.java?rev=947642&r1=947641&r2=947642&view=diff
==============================================================================
--- webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/ext/stax/datahandler/DataHandlerWriter.java (original)
+++ webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/ext/stax/datahandler/DataHandlerWriter.java Mon May 24 13:45:01 2010
@@ -30,9 +30,10 @@ import javax.xml.stream.XMLStreamExcepti
  * implementing this extension may write the binary data as base64 encoded character data
  * or using some optimization such as XOP/MTOM.
  * <p>
- * A consumer MUST use {@link javax.xml.stream.XMLStreamWriter#getProperty(String)} with the property
- * name defined by {@link #PROPERTY} to get a reference to this extension interface. See
- * the package Javadoc for additional requirements.
+ * All the requirements specified in {@link org.apache.axiom.ext.stax} apply to
+ * this extension interface. In particular,
+ * a consumer MUST use {@link javax.xml.stream.XMLStreamWriter#getProperty(String)} with the property
+ * name defined by {@link #PROPERTY} to get a reference to this extension interface.
  * <p>
  * The interface defines two methods to write binary content, one that takes a {@link DataHandler}
  * argument and one with a {@link DataHandlerProvider} argument. The first should be used when

Modified: webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/ext/stax/datahandler/package.html
URL: http://svn.apache.org/viewvc/webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/ext/stax/datahandler/package.html?rev=947642&r1=947641&r2=947642&view=diff
==============================================================================
--- webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/ext/stax/datahandler/package.html (original)
+++ webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/ext/stax/datahandler/package.html Mon May 24 13:45:01 2010
@@ -19,26 +19,7 @@
 <html>
 <body>
 Defines an Axiom specific extension to the StAX API to work with DataHandler objects.
-<p>
-This package defines two extensions, {@link org.apache.axiom.ext.stax.datahandler.DataHandlerReader}
-for {@link javax.xml.stream.XMLStreamReader} and {@link org.apache.axiom.ext.stax.datahandler.DataHandlerWriter}
-for {@link javax.xml.stream.XMLStreamWriter}. The reader or writer wishing to support the
-extension MAY implement the corresponding interface directly, but a consumer MUST use
-the property mechanism to get a reference to this extension interface, i.e. it MUST call
-{@link javax.xml.stream.XMLStreamReader#getProperty(String)} or
-{@link javax.xml.stream.XMLStreamWriter#getProperty(String)}. The two extension interfaces
-define constants with for the property names.
-<p>
-The rationale for this requirement is that a property based approach continues to work even if the
-stream implementing the extension is accessed indirectly through a proxy implementing the
-{@link javax.xml.stream.XMLStreamReader} or {@link javax.xml.stream.XMLStreamWriter} interface but unaware
-of the extensions defined in this package. Note that this assumes that the proxy correctly delegates calls to the
-<code>getProperty</code> methods.
-<p>
-The property returning the extension interface MUST be available regardless of the current state of
-the stream. In addition it is assumed to be immutable, i.e. its value MUST NOT not change during the
-lifetime of the {@link javax.xml.stream.XMLStreamReader} or {@link javax.xml.stream.XMLStreamWriter}
-implementation. For a consumer it is therefore sufficient to look up the extension once and to
-continue using the obtained reference during the entire lifetime of the stream.
+
+@see org.apache.axiom.ext.stax
 </body>
 </html>
\ No newline at end of file

Added: webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/ext/stax/package.html
URL: http://svn.apache.org/viewvc/webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/ext/stax/package.html?rev=947642&view=auto
==============================================================================
--- webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/ext/stax/package.html (added)
+++ webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/ext/stax/package.html Mon May 24 13:45:01 2010
@@ -0,0 +1,44 @@
+<!--
+  ~ Licensed to the Apache Software Foundation (ASF) under one
+  ~ or more contributor license agreements. See the NOTICE file
+  ~ distributed with this work for additional information
+  ~ regarding copyright ownership. The ASF licenses this file
+  ~ to you under the Apache License, Version 2.0 (the
+  ~ "License"); you may not use this file except in compliance
+  ~ with the License. You may obtain a copy of the License at
+  ~
+  ~ http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing,
+  ~ software distributed under the License is distributed on an
+  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  ~ KIND, either express or implied. See the License for the
+  ~ specific language governing permissions and limitations
+  ~ under the License.
+  -->
+<html>
+<body>
+Defines Axiom specific extensions to the StAX API.
+<p>
+This package and its subpackages defines several extensions to the StAX API, more precisely for the
+{@link javax.xml.stream.XMLStreamReader} and {@link javax.xml.stream.XMLStreamWriter} classes.
+The reader or writer wishing to support the
+extension MAY implement the corresponding interface directly, but a consumer MUST use
+the property mechanism to get a reference to this extension interface, i.e. it MUST call
+{@link javax.xml.stream.XMLStreamReader#getProperty(String)} or
+{@link javax.xml.stream.XMLStreamWriter#getProperty(String)}. Each of the extension interfaces in
+this package defines a constant for the property name to use.
+<p>
+The rationale for this requirement is that a property based approach continues to work even if the
+stream implementing the extension is accessed indirectly through a proxy implementing the
+{@link javax.xml.stream.XMLStreamReader} or {@link javax.xml.stream.XMLStreamWriter} interface but unaware
+of the extensions defined in this package. Note that this assumes that the proxy correctly delegates calls to the
+<code>getProperty</code> methods.
+<p>
+The property returning the extension interface MUST be available regardless of the current state of
+the stream. In addition it is assumed to be immutable, i.e. its value MUST NOT not change during the
+lifetime of the {@link javax.xml.stream.XMLStreamReader} or {@link javax.xml.stream.XMLStreamWriter}
+implementation. For a consumer it is therefore sufficient to look up the extension once and to
+continue using the obtained reference during the entire lifetime of the stream.
+</body>
+</html>
\ No newline at end of file