You are viewing a plain text version of this content. The canonical link for it is here.
Posted to axis-cvs@ws.apache.org by ds...@apache.org on 2006/09/15 06:32:06 UTC
svn commit: r446514 - in
/webservices/axis2/trunk/java/modules/kernel/src/org/apache/axis2:
client/Options.java client/ServiceClient.java engine/ListenerManager.java
Author: dsosnoski
Date: Thu Sep 14 21:32:05 2006
New Revision: 446514
URL: http://svn.apache.org/viewvc?view=rev&rev=446514
Log:
Improved JavaDoc comments, minor code cleanup
Modified:
webservices/axis2/trunk/java/modules/kernel/src/org/apache/axis2/client/Options.java
webservices/axis2/trunk/java/modules/kernel/src/org/apache/axis2/client/ServiceClient.java
webservices/axis2/trunk/java/modules/kernel/src/org/apache/axis2/engine/ListenerManager.java
Modified: webservices/axis2/trunk/java/modules/kernel/src/org/apache/axis2/client/Options.java
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/modules/kernel/src/org/apache/axis2/client/Options.java?view=diff&rev=446514&r1=446513&r2=446514
==============================================================================
--- webservices/axis2/trunk/java/modules/kernel/src/org/apache/axis2/client/Options.java (original)
+++ webservices/axis2/trunk/java/modules/kernel/src/org/apache/axis2/client/Options.java Thu Sep 14 21:32:05 2006
@@ -37,15 +37,18 @@
*/
/**
- * The proposal related for this is here :
- * http://marc.theaimsgroup.com/?l=axis2-dev&m=113320384108037&w=2 Client can
- * fill this options and give to any class extending from MEPClient. All those
- * classes will be getting parameters using this.
+ * Holder for operation client options. This is used by the other classes in
+ * this package to configure various aspects of how a client communicates with a
+ * service. It exposes a number of predefined properties as part of the API
+ * (with specific getXXX and setXXX methods), and also allows for arbitrary
+ * named properties to be passed using a properties map with the property name
+ * as the key value. Instances of this class can be chained together for
+ * property inheritance, so that if a property is not set in one instance it
+ * will check its parent for a setting.
*/
public class Options {
-
- public static final String COPY_PROPERTIES = "CopyProperties";
-
+
+ /** Default blocking timeout value. */
public static final int DEFAULT_TIMEOUT_MILLISECONDS = 30 * 1000;
private Options parent;
@@ -92,8 +95,6 @@
*/
protected TransportOutDescription transportOut;
- private String senderTransportProtocol;
-
private EndpointReference to;
//To control , session managment , default is set to true , if user wants he can set that to true
@@ -117,6 +118,11 @@
this.parent = parent;
}
+ /**
+ * Get WS-Addressing Action / SOAP Action string.
+ *
+ * @return action
+ */
public String getAction() {
if (action == null && parent != null) {
return parent.getAction();
@@ -124,6 +130,11 @@
return action;
}
+ /**
+ * Get WS-Addressing FaultTo endpoint reference.
+ *
+ * @return endpoint
+ */
public EndpointReference getFaultTo() {
if (faultTo == null && parent != null) {
return parent.getFaultTo();
@@ -131,6 +142,11 @@
return faultTo;
}
+ /**
+ * Set WS-Addressing From endpoint reference.
+ *
+ * @return endpoint
+ */
public EndpointReference getFrom() {
if (from == null && parent != null) {
return parent.getFrom();
@@ -138,6 +154,11 @@
return from;
}
+ /**
+ * Get listener used for incoming message.
+ *
+ * @return listener
+ */
public TransportListener getListener() {
if (listener == null && parent != null) {
return parent.getListener();
@@ -145,6 +166,11 @@
return listener;
}
+ /**
+ * Get transport used for incoming message.
+ *
+ * @return transport information
+ */
public TransportInDescription getTransportIn() {
if (transportIn == null && parent != null) {
return parent.getTransportIn();
@@ -152,6 +178,11 @@
return transportIn;
}
+ /**
+ * Get transport protocol used for incoming message.
+ *
+ * @return name protocol name ("http", "tcp", etc.)
+ */
public String getTransportInProtocol() {
if (transportInProtocol == null && parent != null) {
return parent.getTransportInProtocol();
@@ -159,6 +190,11 @@
return transportInProtocol;
}
+ /**
+ * Get WS-Addressing MessageId.
+ *
+ * @return uri string
+ */
public String getMessageId() {
if (messageId == null && parent != null) {
return parent.getMessageId();
@@ -167,22 +203,34 @@
return messageId;
}
+ /**
+ * Get a copy of the general option properties. Because of the way options
+ * are stored this does not include properties with specific get/set
+ * methods, only the general properties identified by a text string. The
+ * returned map merges properties inherited from parent options, if any, to
+ * give a complete set of property definitions as seen by users of this
+ * options instance. The returned copy is not "live", so changes you make to
+ * the copy are not reflected in the actual option settings. However, you
+ * can make the modified values take effect with a call to {@link
+ * #setProperties(Map)},
+ *
+ * @return copy of general properties
+ */
public Map getProperties() {
- if (properties.size() == 0 && parent != null) {
- Map properties = parent.getProperties();
-
- if (properties.size() > 0) {
- HashMap ret = new HashMap(properties);
- ret.putAll(properties);
- return ret;
- }
+ if (parent == null) {
+ return new HashMap(properties);
+ } else {
+ Map props = parent.getProperties();
+ props.putAll(properties);
+ return props;
}
- return properties;
}
/**
+ * Get named property value.
+ *
* @param key
- * @return the value realeted to this key. Null, if not found.
+ * @return the value related to this key. <code>null</code>, if not found.
*/
public Object getProperty(String key) {
Object myPropValue = properties.get(key);
@@ -192,6 +240,16 @@
return myPropValue;
}
+ /**
+ * Get WS-Addressing RelatesTo item with a specified type. If there are
+ * multiple RelatesTo items defined with the same type, the one returned
+ * by this method is arbitrary - if you need to handle this case, you can
+ * instead use the {@link #getRelationships()} to retrieve all the items
+ * and check for multiple matches.
+ *
+ * @param type relationship type (URI)
+ * @return item of specified type
+ */
public RelatesTo getRelatesTo(String type) {
if (relationships == null && parent != null) {
return parent.getRelatesTo(type);
@@ -207,8 +265,10 @@
}
/**
- *
- * @return the relates to which has the type http://www.w3.org/2005/08/addressing/reply
+ * Get WS-Addressing RelatesTo item which has the specific type
+ * "http://www.w3.org/2005/08/addressing/reply"
+ *
+ * @return item
*/
public RelatesTo getRelatesTo() {
if (relationships == null && parent != null) {
@@ -225,6 +285,11 @@
return null;
}
+ /**
+ * Get all WS-Addressing RelatesTo items.
+ *
+ * @return array of items
+ */
public RelatesTo[] getRelationships() {
if (relationships == null && parent != null) {
return parent.getRelationships();
@@ -235,10 +300,20 @@
return (RelatesTo[]) relationships.toArray(new RelatesTo[relationships.size()]);
}
+ /**
+ * Set WS-Addressing RelatesTo items.
+ *
+ * @param list
+ */
public void setRelationships(RelatesTo[] list) {
relationships = list == null ? null : Arrays.asList(list);
}
+ /**
+ * Get WS-Addressing ReplyTo endpoint reference.
+ *
+ * @return endpoint
+ */
public EndpointReference getReplyTo() {
if (replyTo == null && parent != null) {
return parent.getReplyTo();
@@ -246,6 +321,11 @@
return replyTo;
}
+ /**
+ * Get outbound transport description.
+ *
+ * @return description
+ */
public TransportOutDescription getTransportOut() {
if (transportOut == null && parent != null) {
return parent.getTransportOut();
@@ -254,14 +334,11 @@
return transportOut;
}
- public String getSenderTransportProtocol() {
- if (senderTransportProtocol == null && parent != null) {
- return parent.getSenderTransportProtocol();
- }
-
- return senderTransportProtocol;
- }
-
+ /**
+ * Get SOAP version being used.
+ *
+ * @return version
+ */
public String getSoapVersionURI() {
if (soapVersionURI == null && parent != null) {
return parent.getSoapVersionURI();
@@ -286,6 +363,11 @@
: timeOutInMilliSeconds;
}
+ /**
+ * Get WS-Addressing To endpoint reference.
+ *
+ * @return endpoint
+ */
public EndpointReference getTo() {
if (to == null && parent != null) {
return parent.getTo();
@@ -301,6 +383,8 @@
* that facility. If this is false, the response message will just be
* returned to the application, irrespective of whether it has a Fault or
* not.
+ *
+ * @return <code>true</code> if exception to be thrown
*/
public boolean isExceptionToBeThrownOnSOAPFault() {
if (isExceptionToBeThrownOnSOAPFault == null && parent != null) {
@@ -311,6 +395,13 @@
|| isExceptionToBeThrownOnSOAPFault.booleanValue();
}
+ /**
+ * Check whether the two SOAP Messages are be sent over same channel or over
+ * separate channels. Only duplex transports such as http and tcp support a
+ * <code>false</code> value.
+
+ * @return separate channel flag
+ */
public boolean isUseSeparateListener() {
if (useSeparateListener == null && parent != null) {
useSeparateListener = parent.useSeparateListener;
@@ -320,14 +411,29 @@
&& useSeparateListener.booleanValue();
}
+ /**
+ * Get parent instance providing default property values.
+ *
+ * @return parent (<code>null</code> if none)
+ */
public Options getParent() {
return parent;
}
+ /**
+ * Set parent instance providing default property values.
+ *
+ * @param parent (<code>null</code> if none)
+ */
public void setParent(Options parent) {
this.parent = parent;
}
+ /**
+ * Set WS-Addressing Action / SOAP Action string.
+ *
+ * @param action
+ */
public void setAction(String action) {
this.action = action;
}
@@ -348,37 +454,64 @@
.valueOf(exceptionToBeThrownOnSOAPFault);
}
+ /**
+ * Set WS-Addressing FaultTo endpoint reference.
+ *
+ * @param faultTo endpoint
+ */
public void setFaultTo(EndpointReference faultTo) {
this.faultTo = faultTo;
}
+ /**
+ * Set WS-Addressing From endpoint reference.
+ *
+ * @param from endpoint
+ */
public void setFrom(EndpointReference from) {
this.from = from;
}
+ /**
+ * Set listener used for incoming message.
+ *
+ * @param listener
+ */
public void setListener(TransportListener listener) {
this.listener = listener;
}
+ /**
+ * Set transport used for incoming message.
+ *
+ * @param transportIn
+ */
public void setTransportIn(TransportInDescription transportIn) {
this.transportIn = transportIn;
}
+ /**
+ * Set transport protocol used for incoming message.
+ *
+ * @param transportInProtocol ("http", "tcp", etc.)
+ */
public void setTransportInProtocol(String transportInProtocol) {
this.transportInProtocol = transportInProtocol;
}
+ /**
+ * Set WS-Addressing MessageId.
+ *
+ * @param messageId URI string
+ */
public void setMessageId(String messageId) {
this.messageId = messageId;
}
/**
- * This will set the properties to the context. But in setting that one may
- * need to "copy" all the properties from the source properties to the
- * target properties. To enable this we introduced a property
- * (org.apache.axis2.client.Options#COPY_PROPERTIES) so that if set to
- * Boolean(true), this code will copy the whole thing, without just
- * referencing to the source.
+ * Set the general property definitions. Due to the way properties are
+ * stored, this will not effect the values of predefined properties with
+ * specific get/set methods.
*
* @param properties
*/
@@ -387,10 +520,9 @@
}
/**
- * Properties you need to pass in to the message context must be set via
- * this. If there is a method to the set this property, within this class,
- * its encouraged to use that method, without duplicating stuff or making
- * room for bugs.
+ * General properties you need to pass in to the message context must be set
+ * via this method. This method can only be used for properties which do not
+ * have specific get/set methods.
*
* @param propertyKey
* @param property
@@ -399,6 +531,11 @@
properties.put(propertyKey, property);
}
+ /**
+ * Add WS-Addressing RelatesTo item.
+ *
+ * @param relatesTo
+ */
public void addRelatesTo(RelatesTo relatesTo) {
if(relationships == null) {
relationships = new ArrayList(5);
@@ -406,18 +543,30 @@
relationships.add(relatesTo);
}
+ /**
+ * Set WS-Addressing ReplyTo endpoint.
+ *
+ * @param replyTo endpoint
+ */
public void setReplyTo(EndpointReference replyTo) {
this.replyTo = replyTo;
}
+ /**
+ * Set transport used for outgoing message.
+ *
+ * @param transportOut
+ */
public void setTransportOut(TransportOutDescription transportOut) {
this.transportOut = transportOut;
}
/**
- * Sets the transport to be used for sending the SOAP Message
+ * Set transport used for outgoing message.
*
- * @param senderTransport
+ * @param senderTransport transport name in Axis2 configuration
+ * ("http", "tcp", etc.)
+ * @param axisConfiguration
* @throws AxisFault if the transport is not found
*/
public void setSenderTransport(String senderTransport,
@@ -431,6 +580,13 @@
}
}
+ /**
+ * Set the SOAP version to be used.
+ *
+ * @param soapVersionURI
+ * @see org.apache.axis2.namespace.Constants#URI_SOAP11_ENV
+ * @see org.apache.axis2.namespace.Constants#URI_SOAP12_ENV
+ */
public void setSoapVersionURI(String soapVersionURI) {
this.soapVersionURI = soapVersionURI;
}
@@ -446,6 +602,11 @@
this.timeOutInMilliSeconds = timeOutInMilliSeconds;
}
+ /**
+ * Set WS-Addressing To endpoint.
+ *
+ * @param to endpoint
+ */
public void setTo(EndpointReference to) {
this.to = to;
}
@@ -455,12 +616,15 @@
* follows: <blockquote>
* <p/>
* <pre>
- * [transportOut, transportIn, useSeparateListener]
+ * [senderTransport, listenerTransport, useSeparateListener]
* http, http, true
* http, http, false
- * http,smtp,true
- * smtp,http,true
- * smtp,smtp,true
+ * http, smtp, true
+ * smtp, http, true
+ * smtp, smtp, true
+ * tcp, tcp, true
+ * tcp, tcp, false
+ * etc.
* </pre>
* <p/>
* </blockquote>
@@ -498,12 +662,11 @@
}
setTransportInProtocol(listenerTransport);
- this.senderTransportProtocol = senderTransport;
}
/**
* Used to specify whether the two SOAP Messages are be sent over same
- * channel or over separate channels.The value of this variable depends on
+ * channel or over separate channels. The value of this variable depends on
* the transport specified. For e.g., if the transports are different this
* is true by default. HTTP transport supports both cases while SMTP
* transport supports only two channel case.
@@ -514,6 +677,13 @@
this.useSeparateListener = Boolean.valueOf(useSeparateListener);
}
+ /**
+ * Add WS-Addressing ReferenceParameter child element. Multiple child
+ * may be used.
+ * TODO Add get method, implement handling.
+ *
+ * @param referenceParameter
+ */
public void addReferenceParameter(OMElement referenceParameter) {
if (referenceParameters == null) {
referenceParameters = new ArrayList(5);
@@ -522,10 +692,22 @@
referenceParameters.add(referenceParameter);
}
+ /**
+ * Check if session management is enabled.
+ *
+ * @return <code>true</code> if enabled
+ */
public boolean isManageSession() {
return manageSession;
}
+ /**
+ * Set session management enabled state. When session management is enabled,
+ * the engine will automatically send session data (such as the service
+ * group id, or HTTP cookies) as part of requests.
+ *
+ * @param manageSession <code>true</code> if enabling sessions
+ */
public void setManageSession(boolean manageSession) {
this.manageSession = manageSession;
}
Modified: webservices/axis2/trunk/java/modules/kernel/src/org/apache/axis2/client/ServiceClient.java
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/modules/kernel/src/org/apache/axis2/client/ServiceClient.java?view=diff&rev=446514&r1=446513&r2=446514
==============================================================================
--- webservices/axis2/trunk/java/modules/kernel/src/org/apache/axis2/client/ServiceClient.java (original)
+++ webservices/axis2/trunk/java/modules/kernel/src/org/apache/axis2/client/ServiceClient.java Thu Sep 14 21:32:05 2006
@@ -38,20 +38,36 @@
import java.util.ArrayList;
/**
- * A ServiceClient class is used to create a client for a service. More details
- * need to be explained here.
+ * Client access to a service. Each instance of this class is associated with a
+ * particular {@link org.apache.axis2.description.AxisService}, and the methods
+ * support operations using that service. {@link Options} instances are used to
+ * configure various aspects of the service access.
*/
public class ServiceClient {
- // service and operation names used for anonymous services and operations
+ /** Base name used for a service created without an existing configuration. */
public static final String ANON_SERVICE = "annonService";
+ /**
+ * Operation name used for an anonymous out-only operation (meaning we send
+ * a message with no response allowed from the service, equivalent to a WSDL
+ * In-Only operation).
+ */
public static final QName ANON_OUT_ONLY_OP = new QName(
"annonOutonlyOp");
+ /**
+ * Operation name used for an anonymous robust-out-only operation
+ * (meaning we send a message, with the only possible response a fault,
+ * equivalent to a WSDL Robust-In-Only operation).
+ */
public static final QName ANON_ROBUST_OUT_ONLY_OP = new QName(
"annonRobustOp");
+ /**
+ * Operation name used for an anonymous in-out operation (meaning we sent a
+ * message and receive a response, equivalent to a WSDL In-Out operation).
+ */
public static final QName ANON_OUT_IN_OP = new QName("annonOutInOp");
// the metadata for the service that I'm clienting for
@@ -86,7 +102,8 @@
*
* @param configContext The configuration context under which this service lives (may
* be null, in which case a new local one will be created)
- * @param axisService The service for which this is the client.
+ * @param axisService The service for which this is the client (may be
+ * <code>null</code>, in which case an anonymous service will be created)
* @throws AxisFault if something goes wrong while creating a config context (if
* needed)
*/
@@ -124,6 +141,7 @@
* We are going to make this policy aware
*
* @param configContext
+ * @param wsdl4jDefinition
* @param wsdlServiceName
* @param portName
* @throws AxisFault
@@ -140,7 +158,7 @@
* wsdl:service element in a WSDL document.
*
* @param configContext The configuration context under which this service lives (may
- * be null, in which case a new local one will be created) *
+ * be <code>null</code>, in which case a new local one will be created) *
* @param wsdlURL The URL of the WSDL document to read
* @param wsdlServiceName The QName of the WSDL service in the WSDL document to create a
* client for
@@ -188,9 +206,8 @@
}
/**
- * Create an anonymous axisService with one (anonymous) operation each for
- * each MEP that I support dealing with anonymously using the convenience
- * APIs.
+ * Create an anonymous axisService with one (anonymous) operation for each
+ * MEP that we support dealing with anonymously using the convenience APIs.
*
* @return the minted anonymous service
*/
@@ -226,36 +243,40 @@
}
/**
- * Set the client configuration related to this service interaction.
+ * Set the basic client configuration related to this service interaction.
*
- * @param options
+ * @param options (non-<code>null</code>)
*/
public void setOptions(Options options) {
this.options = options;
}
/**
- * Get the client configuration from this service interaction.
+ * Get the basic client configuration from this service interaction.
*
- * @return set of options set earlier.
+ * @return options
*/
public Options getOptions() {
return options;
}
/**
- * Set the client configuration related to this service interaction to
- * override any options that the underlying operation client may have.
+ * Set a client configuration to override the normal options used by an
+ * operation client. Any values set in this configuration will be used for
+ * each client, with the standard values for the client still used for any
+ * values not set in the override configuration.
+ *
+ * @param overrideOptions
*/
public void setOverrideOptions(Options overrideOptions) {
this.overrideOptions = overrideOptions;
}
/**
- * Get the client configuration from this service interaction which have
- * been used to overide operation client options as well.
+ * Get the client configuration used to override the normal options set by
+ * an operation client.
*
- * @return set of options set earlier.
+ * @return override options
*/
public Options getOverrideOptions() {
return overrideOptions;
@@ -264,7 +285,7 @@
/**
* Engage a module for this service client.
*
- * @param moduleName Name of the module to engage
+ * @param moduleName name of the module to engage
* @throws AxisFault if something goes wrong
*/
public void engageModule(QName moduleName) throws AxisFault {
@@ -284,11 +305,10 @@
}
/**
- * Add an XML element as a header to be sent with interactions. This allows
- * users to go a bit beyond the dirt simple XML in/out pattern using this
- * simplified API. A header
+ * Add an arbitrary XML element as a header to be sent with outgoing
+ * messages.
*
- * @param header The header to be added for interactions. Must not be null.
+ * @param header header to be sent (non-<code>null</code>)
*/
public void addHeader(OMElement header) {
if (headers == null) {
@@ -298,9 +318,9 @@
}
/**
- * This will let the user to add SOAP Headers to the out going message
+ * Add SOAP Header to be sent with outgoing messages.
*
- * @param header
+ * @param header header to be sent (non-<code>null</code>)
*/
public void addHeader(SOAPHeaderBlock header) {
if (headers == null) {
@@ -310,8 +330,7 @@
}
/**
- * To remove all the
- * in ServiceClient
+ * Remove all headers for outgoing message.
*/
public void removeHeaders() {
if (headers != null) {
@@ -326,6 +345,7 @@
*
* @param headerName
* @param headerText
+ * @throws AxisFault
*/
public void addStringHeader(QName headerName, String headerText) throws AxisFault {
if (headerName.getNamespaceURI() == null || "".equals(headerName.getNamespaceURI())) {
@@ -338,14 +358,14 @@
}
/**
- * This is a simple client API to invoke a service operation who's MEP is
- * Robust In-Only. This API can be used to simply send a bit of XML and
- * possibly receive a fault. If you need more control over this interaction
- * then you need to create a client (@see createClient()) for the operation
- * and use that instead.
- *
- * @param elem The XML to send
- * @throws AxisFault if something goes wrong while sending it or if a fault is
+ * Directly invoke an anonymous operation with a Robust In-Only MEP. This
+ * method just sends your supplied XML and possibly receives a fault. For
+ * more control, you can instead create a client for the operation and use
+ * that client to execute the send.
+ *
+ * @see #createClient(QName)
+ * @param elem XML to send
+ * @throws AxisFault if something goes wrong while sending, or if a fault is
* received in response (per the Robust In-Only MEP).
*/
public void sendRobust(OMElement elem) throws AxisFault {
@@ -353,14 +373,14 @@
}
/**
- * This is a simple client API to invoke a service operation who's MEP is
- * Robust In-Only. This API can be used to simply send a bit of XML and
- * possibly receive a fault under the guise of a specific operation. If you
- * need more control over this interaction then you need to create a client
- * (@see createClient()) for the operation and use that instead.
- *
- * @param operation The name of the operation to use. Must NOT be null.
- * @param elem The XML to send
+ * Directly invoke a named operation with a Robust In-Only MEP. This method
+ * just sends your supplied XML and possibly receives a fault. For more
+ * control, you can instead create a client for the operation and use that
+ * client to execute the send.
+ *
+ * @see #createClient(QName)
+ * @param operation name of operation to be invoked (non-<code>null</code>)
+ * @param elem XML to send
* @throws AxisFault if something goes wrong while sending it or if a fault is
* received in response (per the Robust In-Only MEP).
*/
@@ -427,28 +447,31 @@
}
/**
- * Send a bit of XML and forget about it. This API is used to interact with
- * a service operation who's MEP is In-Only. That is, there is no
- * opportunity to get an error from the service via this API; one may still
- * get client-side errors, such as host unknown etc.
- *
- * @param elem The XML element to send to the service
- * @throws AxisFault If something goes wrong trying to send the XML
+ * Directly invoke an anonymous operation with an In-Only MEP. This method
+ * just sends your supplied XML without the possibility of any response from
+ * the service (even an error - though you can still get client-side errors
+ * such as "Host not found"). For more control, you can instead create a
+ * client for the operation and use that client to execute the send.
+ *
+ * @see #createClient(QName)
+ * @param elem XML to send
+ * @throws AxisFault ff something goes wrong trying to send the XML
*/
public void fireAndForget(OMElement elem) throws AxisFault {
fireAndForget(ANON_OUT_ONLY_OP, elem);
}
/**
- * Send a bit of XML and forget about it under the guise of a specific
- * operation. This API is used to interact with a service operation who's
- * MEP is In-Only. That is, there is no opportunity to get an error from the
- * service via this API; one may still get client-side errors, such as host
- * unknown etc.
- *
- * @param operation The operation to send fire the message under
- * @param elem The XML element to send to the service
- * @throws AxisFault If something goes wrong trying to send the XML
+ * Directly invoke a named operation with an In-Only MEP. This method just
+ * sends your supplied XML without the possibility of any response from the
+ * service (even an error - though you can still get client-side errors such
+ * as "Host not found"). For more control, you can instead create a client
+ * for the operation and use that client to execute the send.
+ *
+ * @see #createClient(QName)
+ * @param operation name of operation to be invoked (non-<code>null</code>)
+ * @param elem XML to send
+ * @throws AxisFault if something goes wrong trying to send the XML
*/
public void fireAndForget(QName operation, OMElement elem) throws AxisFault {
// look up the appropriate axisop and create the client
@@ -463,10 +486,14 @@
}
/**
- * This will allow user to do a send and receive invocation just providing the payload.
+ * Directly invoke an anonymous operation with an In-Out MEP. This method
+ * sends your supplied XML and receives a response. For more control, you
+ * can instead create a client for the operation and use that client to
+ * execute the exchange.
*
+ * @see #createClient(QName)
* @param elem
- * @return
+ * @return response
* @throws AxisFault
*/
public OMElement sendReceive(OMElement elem) throws AxisFault {
@@ -474,11 +501,14 @@
}
/**
- * Do send receive invocation giving the payload and the operation QName.
+ * Directly invoke a named operation with an In-Out MEP. This method sends
+ * your supplied XML and receives a response. For more control, you can
+ * instead create a client for the operation and use that client to execute
+ * the exchange.
*
- * @param operation
+ * @param operation name of operation to be invoked (non-<code>null</code>)
* @param elem
- * @return
+ * @return response
* @throws AxisFault
*/
public OMElement sendReceive(QName operation, OMElement elem)
@@ -544,9 +574,13 @@
}
/**
- * Invoke send and receive just providing the payload and the call back handler. This will ease
- * the user by not requiring him to provide an operation name
+ * Directly invoke an anonymous operation with an In-Out MEP without waiting
+ * for a response. This method sends your supplied XML with response
+ * notification to your callback handler. For more control, you can instead
+ * create a client for the operation and use that client to execute the
+ * exchange.
*
+ * @see #createClient(QName)
* @param elem
* @param callback
* @throws AxisFault
@@ -557,9 +591,14 @@
}
/**
- * Do a blocking send and receive invocation.
+ * Directly invoke a named operation with an In-Out MEP without waiting for
+ * a response. This method sends your supplied XML with response
+ * notification to your callback handler. For more control, you can instead
+ * create a client for the operation and use that client to execute the
+ * exchange.
*
- * @param operation
+ * @see #createClient(QName)
+ * @param operation name of operation to be invoked (non-<code>null</code>)
* @param elem
* @param callback
* @throws AxisFault
@@ -584,17 +623,17 @@
}
/**
- * Create a MEP client for a specific operation. This is the way one can
- * create a full function MEP client which can be used to exchange messages
- * for this specific operation. If you're using this then you must know what
- * you're doing and need the full capabilities of Axis2's client
- * architecture. This is meant for people with deep skin and not the light
- * user.
- *
- * @param operation The QName of the operation to create a client for.
- * @return a MEP client configured to talk to the given operation or null if
- * the operation name is not found.
- * @throws AxisFault if the operation is not found or something else goes wrong
+ * Create an operation client with the appropriate message exchange pattern
+ * (MEP). This method creates a full-function MEP client which can be used
+ * to exchange messages for a specific operation. It configures the
+ * constructed operation client to use the current normal and override
+ * options. This method is used internally, and also by generated client
+ * stub code.
+ *
+ * @param operation qualified name of operation (local name is operation
+ * name, namespace URI is just the empty string)
+ * @return client configured to talk to the given operation
+ * @throws AxisFault if the operation is not found
*/
public OperationClient createClient(QName operation) throws AxisFault {
AxisOperation axisOp = axisService.getOperation(operation);
@@ -616,8 +655,10 @@
}
/**
- * This will close the out put stream or , and remove entry from waiting
- * queue of the transport Listener queue.
+ * Stops the transports and shuts down modules. This should only be called
+ * when you're done using all instances of this class created for a
+ * particular {@link org.apache.axis2.context.ConfigurationContext}, since
+ * all these instances will share a common set of listeners and modules.
*
* @throws AxisFault
*/
@@ -626,9 +667,11 @@
}
/**
- * Return the SOAP factory to use depending on what options have been set
- * (or default to SOAP 1.1)
+ * Return the SOAP factory to use depending on what options have been set.
+ * If the SOAP version has not be seen in the options, version 1.1 is the
+ * default.
*
+ * @see Options#setSoapVersionURI()
* @return the SOAP factory
*/
private SOAPFactory getSOAPFactory() {
@@ -636,7 +679,7 @@
if (SOAP12Constants.SOAP_ENVELOPE_NAMESPACE_URI.equals(soapVersionURI)) {
return OMAbstractFactory.getSOAP12Factory();
} else {
- // make the SOAP 1.2 the default SOAP version
+ // make the SOAP 1.1 the default SOAP version
return OMAbstractFactory.getSOAP11Factory();
}
}
@@ -661,6 +704,11 @@
}
+ /**
+ * Add all configured headers to a SOAP envelope.
+ *
+ * @param envelope
+ */
public void addHeadersToEnvelope(SOAPEnvelope envelope) {
if (headers != null) {
SOAPHeader sh = envelope.getHeader();
@@ -672,10 +720,10 @@
/**
- * To get the EPR that the service is running
- * transport : can be null , if it is null then epr will be craetd using any available
- * transports
- *
+ * Get the endpoint reference for this client using a particular transport.
+ *
+ * @param transport transport name (non-<code>null</code>)
+ * @return local endpoint
* @throws AxisFault
*/
public EndpointReference getMyEPR(String transport) throws AxisFault {
@@ -683,16 +731,19 @@
}
/**
- * To get the Targert EPR if any in service conetext
- * and reference paramters in TEPR can send back , in the same time this epr can use to manage
- * session across mutiple ServiceClient
+ * Get the endpoint reference for the service.
*
- * @return <code>EndpointReference</code>
+ * @return service endpoint
*/
public EndpointReference getTargetEPR() {
return serviceContext.getTargetEPR();
}
+ /**
+ * Set the endpoint reference for the service.
+ *
+ * @param targetEpr
+ */
public void setTargetEPR(EndpointReference targetEpr) {
serviceContext.setTargetEPR(targetEpr);
}
@@ -735,9 +786,9 @@
}
/**
- * To get the service context.
+ * Get the service context.
*
- * @return ServiceContext
+ * @return context
*/
public ServiceContext getServiceContext() {
return serviceContext;
@@ -749,22 +800,21 @@
}
/**
- * This will remove axissrevice , if it is passed configuration context into it.
- * The problem is if some one keep of on creating service client by giving
- * configuration conetxt and null aixsService , in that case it SC will
- * create new axisServices and add that into axisConfig , so to remove the
- * one that this particular SC instance create one can use this method.
+ * Clean up configuration created with this client. Call this method when
+ * you're done using the client, in order to discard any associated
+ * resources.
*
* @throws AxisFault
*/
public void cleanup() throws AxisFault {
+ // if a configuration context was created for this client there'll also
+ // be a service group, so discard that
if (!createConfigCtx) {
String serviceGroupName = ((AxisServiceGroup) axisService.getParent()).getServiceGroupName();
AxisConfiguration axisConfiguration = configContext.getAxisConfiguration();
AxisServiceGroup asg = axisConfiguration.getServiceGroup(serviceGroupName);
if (asg != null) {
- axisConfiguration.removeServiceGroup(
- serviceGroupName);
+ axisConfiguration.removeServiceGroup(serviceGroupName);
}
}
}
Modified: webservices/axis2/trunk/java/modules/kernel/src/org/apache/axis2/engine/ListenerManager.java
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/modules/kernel/src/org/apache/axis2/engine/ListenerManager.java?view=diff&rev=446514&r1=446513&r2=446514
==============================================================================
--- webservices/axis2/trunk/java/modules/kernel/src/org/apache/axis2/engine/ListenerManager.java (original)
+++ webservices/axis2/trunk/java/modules/kernel/src/org/apache/axis2/engine/ListenerManager.java Thu Sep 14 21:32:05 2006
@@ -141,7 +141,7 @@
}
/**
- * To stop all the transports
+ * Stop all the transports and notify modules of shutdown.
*/
public synchronized void stop() throws AxisFault {
Iterator itr_st = startedTransports.values().iterator();
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org