svn commit: r448741 - /webservices/axis2/trunk/java/modules/kernel/src/org/apache/axis2/client/Stub.java

[ds...@apache.org]

Author: dsosnoski
Date: Thu Sep 21 16:44:44 2006
New Revision: 448741

URL: http://svn.apache.org/viewvc?view=rev&rev=448741
Log:
Javadoc updates

Modified:
    webservices/axis2/trunk/java/modules/kernel/src/org/apache/axis2/client/Stub.java

Modified: webservices/axis2/trunk/java/modules/kernel/src/org/apache/axis2/client/Stub.java
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/modules/kernel/src/org/apache/axis2/client/Stub.java?view=diff&rev=448741&r1=448740&r2=448741
==============================================================================
--- webservices/axis2/trunk/java/modules/kernel/src/org/apache/axis2/client/Stub.java (original)
+++ webservices/axis2/trunk/java/modules/kernel/src/org/apache/axis2/client/Stub.java Thu Sep 21 16:44:44 2006
@@ -17,26 +17,31 @@
 
 package org.apache.axis2.client;
 
+import java.util.ArrayList;
+
+import javax.xml.stream.XMLStreamReader;
+
 import org.apache.axiom.om.OMAbstractFactory;
 import org.apache.axiom.om.OMElement;
 import org.apache.axiom.om.impl.builder.StAXOMBuilder;
 import org.apache.axiom.om.impl.llom.factory.OMXMLBuilderFactory;
 import org.apache.axiom.soap.SOAP11Constants;
 import org.apache.axiom.soap.SOAP12Constants;
-import org.apache.axiom.soap.SOAPBody;
 import org.apache.axiom.soap.SOAPEnvelope;
 import org.apache.axiom.soap.SOAPFactory;
 import org.apache.axiom.soap.SOAPProcessingException;
+import org.apache.axis2.AxisFault;
 import org.apache.axis2.description.AxisService;
 import org.apache.axis2.i18n.Messages;
-import org.apache.axis2.wsdl.WSDLConstants;
-import org.apache.axis2.AxisFault;
 
-import javax.xml.stream.XMLStreamReader;
-import java.util.ArrayList;
-
-public abstract class
-        Stub {
+/**
+ * Base class for generated client stubs. This defines several client API
+ * (<code>public</code>) methods shared between all types of stubs, along with
+ * some <code>protected</code> methods intended for use by the actual stub
+ * implementation code. The client API method names start with a leading
+ * underscore character to avoid conflicts with actual implementation methods.
+ */
+public abstract class Stub {
 
     protected AxisService _service;
     protected ArrayList modules = new ArrayList();
@@ -44,27 +49,60 @@
 
     protected ServiceClient _serviceClient;
 
+    /**
+     * Get service client implementation used by this stub.
+     * 
+     * @return service client
+     */
     public ServiceClient _getServiceClient() {
         return _serviceClient;
     }
 
+    /**
+     * Set service client implementation used by this stub. Once set, the
+     * service client is owned by this stub and will automatically be removed
+     * from the configuration when use of the stub is done.
+     * 
+     * @param _serviceClient
+     */
     public void _setServiceClient(ServiceClient _serviceClient) {
         this._serviceClient = _serviceClient;
     }
 
-    protected SOAPEnvelope createEnvelope(Options options) throws SOAPProcessingException {
+    /**
+     * Create a SOAP message envelope using the supplied options.
+     * TODO generated stub code should use this method, or similar method taking
+     * an operation client
+     * 
+     * @param options
+     * @return generated 
+     * @throws SOAPProcessingException
+     */
+    protected static SOAPEnvelope createEnvelope(Options options) throws SOAPProcessingException {
         return getFactory(options.getSoapVersionURI()).getDefaultEnvelope();
     }
 
-
-    protected OMElement getElementFromReader(XMLStreamReader reader) {
+    /**
+     * Read a root element from the parser.
+     * TODO generated stub code should use this method
+     * 
+     * @param reader
+     * @return root element
+     */
+    protected static OMElement getElementFromReader(XMLStreamReader reader) {
         StAXOMBuilder builder =
                 OMXMLBuilderFactory.createStAXOMBuilder(OMAbstractFactory.getOMFactory(), reader);
 
         return builder.getDocumentElement();
     }
 
-    protected SOAPFactory getFactory(String soapVersionURI) {
+    /**
+     * Get Axiom factory appropriate to selected SOAP version.
+     * 
+     * @param soapVersionURI
+     * @return factory
+     */
+    protected static SOAPFactory getFactory(String soapVersionURI) {
 
         if (SOAP11Constants.SOAP_ENVELOPE_NAMESPACE_URI.equals(soapVersionURI)) {
             return OMAbstractFactory.getSOAP11Factory();
@@ -77,7 +115,9 @@
     }
 
     /**
-     * Finalize overridden to cleanup
+     * Finalize method called by garbage collection. This is overridden to
+     * support cleanup of any associated resources.
+     * 
      * @throws Throwable
      */
     protected void finalize() throws Throwable {
@@ -86,11 +126,12 @@
     }
 
     /**
-     * Cleanup by removing the axis service
+     * Cleanup associated resources. This removes the axis service from the
+     * configuration.
+     * 
      * @throws AxisFault
      */
     public void cleanup() throws AxisFault {
         _service.getAxisConfiguration().removeService(_service.getName());
     }
-
 }



---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org