mq5.0-source.main.jaxm-api.src.main.java.javax.xml.messaging.ProviderConnection Maven / Gradle / Ivy
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2000-2012 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
package javax.xml.messaging;
import javax.xml.soap.*;
/**
* A client's active connection to its messaging provider.
*
* A ProviderConnection object is created using a
* ProviderConnectionFactory object, which is configured so that
* the connections it creates will be to a particular messaging provider.
* To create a connection, a client first needs to obtain an instance of
* the ProviderConnectionFactory class that creates connections to
* the desired messaging provider. The client then calls the
* createConnection method on it.
*
* The information necessary to set up a ProviderConnectionFactory
* object that creates connections to a particular messaging provider is
* supplied at deployment time. Typically an instance of
* ProviderConnectionFactory will be bound to a logical
* name in a naming service. Later the client can do a lookup on the
* logical name to retrieve an instance of the
* ProviderConnectionFactory class that produces
* connections to its messaging provider.
*
* The following code fragment is an example of a client doing a lookup of
* a ProviderConnectionFactory object and then using it to create
* a connection. The first two lines in this example use the
* JavaTM Naming and Directory
* Interface (JNDI) to create a context, which is then used to do
* the lookup. The argument provided to the lookup method
* is the logical name that was previously associated with the
* desired messaging provider. The lookup method returns
* a Java Object, which needs to be cast to a
* ProviderConnectionFactory object before it can be used to create
* a connection. In the following code fragment, the resulting
* ProviderConnection object is a connection to the messaging provider
* that is associated with the logical name "ProviderXYZ".
*
* Context ctx = new InitialContext();
* ProviderConnectionFactory pcf = (ProviderConnectionFactory)ctx.lookup("ProviderXYZ");
* ProviderConnection con = pcf.createConnection();
*
*
*
* After the client has obtained a connection to its messaging provider,
* it can use that connection to create one or more
* MessageFactory objects, which can then be used to create
* SOAPMessage objects.
* Messages are delivered to an endpoint using the ProviderConnection
* method send.
*
*
* The messaging provider maintains a list of Endpoint objects,
* which is established at deployment time as part of configuring
* the messaging provider. When a client uses a messaging provider to send
* messages, it can
* send messages only to those parties represented by Endpoint
* objects in its messaging provider's list. This is true because the
* messaging provider maps the URI for each Endpoint object to
* a URL.
*
* Note that it is possible for a client to send a message without
* using a messaging provider. In this case, the client uses a
* SOAPConnection object
* to send point-to-point messages via the method call.
* This method takes an Endpoint object (actually a
* URLEndpoint object) that specifies the URL where the message
* is to be sent. See {@link SOAPConnection} and
* {@link URLEndpoint} for more information.
*
* Typically, because clients have one messaging provider, they will do all
* their messaging with a single ProviderConnection object. It is
* possible, however, for a sophisticated application to use multiple
* connections.
*
*
* Generally, a container is configured with a listener component at
* deployment time using an implementation-specific mechanism.
* A client running in such a container uses a OnewayListener
* object to receive messages asynchronously. In this scenario, messages are
* sent via the ProviderConnection method send.
* A client running in a container that wants to receive synchronous messages
* uses a ReqRespListener object. A ReqRespListener
* object receives messages sent via the SOAPConnection method
* call.
*
* Due to the authentication and communication setup done when a
* ProviderConnection object is created, it is a relatively heavy-weight
* object. Therefore, a client should close its connection as soon as it is
* done using it.
*
* JAXM objects created using one ProviderConnection object cannot be
* used with a different ProviderConnection object.
*/
public interface ProviderConnection {
/**
* Retrieves the ProviderMetaData object that contains
* information about the messaging provider to which this
* ProviderConnection object is connected.
*
* @return the ProviderMetaData object with information
* about the messaging provider
* @exception JAXMException if there is a problem getting the
* ProviderMetaData object
*
* @see javax.xml.messaging.ProviderMetaData
*
*/
public ProviderMetaData getMetaData() throws JAXMException;
/**
* Closes this ProviderConnection object, freeing its resources
* and making it immediately available for garbage collection.
* Since a provider typically allocates significant resources outside
* the JVM on behalf of a connection, clients should close connections
* when they are not needed. Relying on garbage collection to eventually
* reclaim these resources may not be timely enough.
*
* @exception JAXMException if a JAXM error occurs while closing
* the connection.
*/
public void close() throws JAXMException;
/**
* Creates a MessageFactory object that will produce
* SOAPMessage objects for the given profile. The
* MessageFactory object that is returned can create
* instances of SOAPMessage subclasses as appropriate for
* the given profile.
*
* @param profile a string that represents a particular JAXM
* profile in use. An example of a JAXM profile is:
* "ebxml".
*
* @return a new MessageFactory object that will create
* SOAPMessage objects for the given profile
* @exception JAXMException if the JAXM infrastructure encounters
* an error, for example, if the endpoint
* that is being used is not compatible
* with the specified profile
*/
public MessageFactory createMessageFactory(String profile)
throws JAXMException;
/**
* Sends the given SOAPMessage object and returns immediately
* after handing the message over to the
* messaging provider. No assumptions can be made regarding the ultimate
* success or failure of message delivery at the time this method returns.
*
* @param message the SOAPMessage object that is to be
* sent asynchronously over this ProviderConnection object
* @exception JAXMException if a JAXM transmission error occurs
*
*/
public void send(SOAPMessage message)
throws JAXMException;
}