Home » xml-commons-external-1.4.01-src » javax » xml » messaging » [javadoc | source]

    1   /*
    2    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    3    *
    4    * Copyright 2000-2007 Sun Microsystems, Inc. All rights reserved. 
    5    *
    6    * The contents of this file are subject to the terms of either the GNU
    7    * General Public License Version 2 only ("GPL") or the Common Development
    8    * and Distribution License ("CDDL") (collectively, the "License").  You may
    9    * not use this file except in compliance with the License.  You can obtain
   10    * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
   11    * or mq/legal/LICENSE.txt.  See the License for the specific language
   12    * governing permissions and limitations under the License.
   13    * 
   14    * When distributing the software, include this License Header Notice in each
   15    * file and include the License file at mq/legal/LICENSE.txt.  Sun designates
   16    * this particular file as subject to the "Classpath" exception as provided by
   17    * Sun in the GPL Version 2 section of the License file that accompanied this
   18    * code.  If applicable, add the following below the License Header, with the
   19    * fields enclosed by brackets [] replaced by your own identifying information:
   20    * "Portions Copyrighted [year] [name of copyright owner]"
   21    * 
   22    * Contributor(s):
   23    * 
   24    * If you wish your version of this file to be governed by only the CDDL or
   25    * only the GPL Version 2, indicate your decision by adding "[Contributor]
   26    * elects to include this software in this distribution under the [CDDL or GPL
   27    * Version 2] license."  If you don't indicate a single choice of license, a
   28    * recipient has the option to distribute your version of this file under
   29    * either the CDDL, the GPL Version 2 or  to extend the choice of license to
   30    * its licensees as provided above.  However, if you add GPL Version 2 code
   31    * and therefore, elected the GPL Version 2 license, then the option applies
   32    * only if the new code is made subject to such option by the copyright holder. 
   33    */
   34   
   35   /*
   36    * @(#)ProviderConnection.java	1.3 07/02/07
   37    */ 
   38   
   39   package javax.xml.messaging;
   40   
   41   import javax.xml.soap;
   42   
   43   /**
   44    * A client's active connection to its messaging provider.
   45    * <P>
   46    * A <code>ProviderConnection</code> object is created using a
   47    * <code>ProviderConnectionFactory</code> object, which is configured so that
   48    * the connections it creates will be to a particular messaging provider.
   49    * To create a connection, a client first needs to obtain an instance of
   50    * the <code>ProviderConnectionFactory</code> class that creates connections to
   51    * the desired messaging provider. The client then calls the
   52    * <code>createConnection</code> method on it.
   53    * <P>
   54    * The information necessary to set up a <code>ProviderConnectionFactory</code>
   55    * object that creates connections to a particular messaging provider is 
   56    * supplied at deployment time.  Typically an instance of
   57    * <code>ProviderConnectionFactory</code> will be bound to a logical
   58    * name in a naming service. Later the client can do a lookup on the
   59    * logical name to retrieve an instance of the
   60    * <code>ProviderConnectionFactory</code> class that produces
   61    * connections to its messaging provider.
   62    * <P>
   63    * The following code fragment is an example of a client doing a lookup of
   64    * a <code>ProviderConnectionFactory</code> object and then using it to create
   65    * a connection.  The first two lines in this example use the 
   66    * Java<sup><font size =-2>TM</font></sup> Naming and Directory
   67    * Interface (JNDI) to create a context, which is then used to do
   68    * the lookup.  The argument provided to the <code>lookup</code> method
   69    * is the logical name that was previously associated with the
   70    * desired messaging provider. The <code>lookup</code> method returns
   71    * a Java <code>Object</code>, which needs to be cast to a
   72    * <code>ProviderConnectionFactory</code> object before it can be used to create
   73    * a connection.  In the following code fragment, the resulting 
   74    * <code>ProviderConnection</code> object is a connection to the messaging provider
   75    * that is associated with the logical name "ProviderXYZ".
   76    * <PRE>
   77    *    Context ctx = new InitialContext();
   78    *    ProviderConnectionFactory pcf = (ProviderConnectionFactory)ctx.lookup("ProviderXYZ");
   79    *    ProviderConnection con = pcf.createConnection();
   80    * </PRE>
   81    *
   82    * <P>
   83    * After the client has obtained a connection to its messaging provider,
   84    * it can use that connection to create one or more 
   85    * <code>MessageFactory</code> objects, which can then be used to create
   86    * <code>SOAPMessage</code> objects.
   87    * Messages are delivered to an endpoint using the <code>ProviderConnection</code>
   88    * method <code>send</code>. 
   89    *
   90    * <P>
   91    * The messaging provider maintains a list of <code>Endpoint</code> objects,
   92    * which is established at deployment time as part of configuring 
   93    * the messaging provider. When a client uses a messaging provider to send
   94    * messages, it can 
   95    * send messages only to those parties represented by <code>Endpoint</code> 
   96    * objects in its messaging provider's list. This is true because the
   97    * messaging provider maps the URI for each <code>Endpoint</code> object to
   98    * a URL.  
   99    * <P>
  100    * Note that it is possible for a client to send a message without
  101    * using a messaging provider.  In this case, the client uses a
  102    * <code>SOAPConnection</code> object 
  103    * to send point-to-point messages via the method <code>call</code>.
  104    * This method takes an <code>Endpoint</code> object (actually a
  105    * <code>URLEndpoint</code> object) that specifies the URL where the message
  106    * is to be sent.  See {@link SOAPConnection} and
  107    * {@link URLEndpoint} for more information.
  108    * <P>
  109    * Typically, because clients have one messaging provider, they will do all 
  110    * their messaging with a single <code>ProviderConnection</code> object. It is 
  111    * possible, however, for a sophisticated application to use multiple
  112    * connections. 
  113    *
  114    * <P>
  115    * Generally, a container is configured with a listener component at
  116    * deployment time using an implementation-specific mechanism. 
  117    * A client running in such a container uses a <code>OnewayListener</code>
  118    * object to receive messages asynchronously. In this scenario, messages are
  119    * sent via the <code>ProviderConnection</code> method <code>send</code>.
  120    * A client running in a container that wants to receive synchronous messages
  121    * uses a <code>ReqRespListener</code> object. A <code>ReqRespListener</code>
  122    * object receives messages sent via the <code>SOAPConnection</code> method
  123    * <code>call</code>.
  124    * <P>
  125    * Due to the authentication and communication setup done when a 
  126    * <code>ProviderConnection</code> object is created, it is a relatively heavy-weight 
  127    * object. Therefore, a client should close its connection as soon as it is
  128    * done using it.
  129    * <P>
  130    * JAXM objects created using one <code>ProviderConnection</code> object cannot be 
  131    * used with a different <code>ProviderConnection</code> object.
  132    */
  133   public interface ProviderConnection {
  134   
  135       /**
  136        * Retrieves the <code>ProviderMetaData</code> object that contains
  137        * information about the messaging provider to which this
  138        * <code>ProviderConnection</code> object is connected.
  139        *
  140        * @return the <code>ProviderMetaData</code> object with information
  141        *         about the messaging provider
  142        * @exception JAXMException if there is a problem getting the 
  143        *            <code>ProviderMetaData</code> object
  144        *
  145        * @see javax.xml.messaging.ProviderMetaData
  146        *
  147        */
  148       public ProviderMetaData getMetaData() throws JAXMException;
  149   
  150       /**
  151        * Closes this <code>ProviderConnection</code> object, freeing its resources
  152        * and making it immediately available for garbage collection.
  153        * Since a provider typically allocates significant resources outside
  154        * the JVM on behalf of a connection, clients should close connections
  155        * when they are not needed. Relying on garbage collection to eventually
  156        * reclaim these resources may not be timely enough.
  157        *
  158        * @exception JAXMException if a JAXM error occurs while closing
  159        *                          the connection. 
  160        */
  161       public void close() throws JAXMException; 
  162   
  163   
  164       /**
  165        * Creates a <code>MessageFactory</code> object that will produce
  166        * <code>SOAPMessage</code> objects for the given profile. The
  167        * <code>MessageFactory</code> object that is returned can create
  168        * instances of <code>SOAPMessage</code> subclasses as appropriate for
  169        * the given profile.
  170        *
  171        * @param profile a string that represents a particular JAXM
  172        *                profile in use. An example of a JAXM profile is:
  173        *                "ebxml".
  174        *
  175        * @return a new <code>MessageFactory</code> object that will create
  176        *         <code>SOAPMessage</code> objects for the given profile
  177        * @exception JAXMException if the JAXM infrastructure encounters
  178        *                          an error, for example, if the endpoint
  179        *                          that is being used is not compatible
  180        *                          with the specified profile
  181        */
  182       public MessageFactory createMessageFactory(String profile)
  183           throws JAXMException;
  184   
  185       /**
  186        * Sends the given <code>SOAPMessage</code> object and returns immediately 
  187        * after handing the message over to the
  188        * messaging provider. No assumptions can be made regarding the ultimate
  189        * success or failure of message delivery at the time this method returns.
  190        * 
  191        * @param message the <code>SOAPMessage</code> object that is to be
  192        *        sent asynchronously over this <code>ProviderConnection</code> object
  193        * @exception JAXMException if a JAXM transmission error occurs
  194        *
  195        */ 
  196       public void send(SOAPMessage message) 
  197           throws JAXMException;
  198   }
  199   

Home » xml-commons-external-1.4.01-src » javax » xml » messaging » [javadoc | source]