Connection (Java EE 5)

连接支持并发使用。

连接有几个用途：

• 它封装与 JMS 提供者的开放连接。它通常表示客户端与服务提供者软件之间的一个开放式 TCP/IP 套接字。
• 它在进行客户端验证的地方创建。
• 它可以指定唯一客户端标识符。
• 它提供一个 ConnectionMetaData 对象。
• 它支持可选的 ExceptionListener 对象。

由于连接的创建涉及设置验证和通信，因此连接是一个相对重量级的对象。大多数客户端都将使用单个连接进行所有消息传送。其他更高级的应用程序可能使用几个连接。JMS API 没有解释使用多个连接的原因；不过，这么做可能是出于某些操作原因。

JMS 客户端通常创建一个连接、一个或多个会话，以及一定数量的消息生成方和使用方。连接创建时，它处于停止模式。这意味着没有消息被传送。

在设置完成之前（也就是，创建完所有消息使用方之前），连接通常处于停止模式。完成设置后，客户端调用连接的 start 方法，消息开始到达该连接的使用方。此设置约定会最大限度地减小客户端仍处于自身设置过程中时由于异步消息传送可能导致的客户端混乱。

可以立即启动连接，随后完成设置。执行该操作的客户端必须准备好处理在其仍处于设置过程中时进行的异步消息传送。

消息生成方可以在连接停止时发送消息。

A Connection object is a client's active connection to its JMS provider. It typically allocates provider resources outside the Java virtual machine (JVM).

Connections support concurrent use.

A connection serves several purposes:

• It encapsulates an open connection with a JMS provider. It typically represents an open TCP/IP socket between a client and the service provider software.
• Its creation is where client authentication takes place.
• It can specify a unique client identifier.
• It provides a ConnectionMetaData object.
• It supports an optional ExceptionListener object.

Because the creation of a connection involves setting up authentication and communication, a connection is a relatively heavyweight object. Most clients will do all their messaging with a single connection. Other more advanced applications may use several connections. The JMS API does not architect a reason for using multiple connections; however, there may be operational reasons for doing so.

A JMS client typically creates a connection, one or more sessions, and a number of message producers and consumers. When a connection is created, it is in stopped mode. That means that no messages are being delivered.

It is typical to leave the connection in stopped mode until setup is complete (that is, until all message consumers have been created). At that point, the client calls the connection's start method, and messages begin arriving at the connection's consumers. This setup convention minimizes any client confusion that may result from asynchronous message delivery while the client is still in the process of setting itself up.

A connection can be started immediately, and the setup can be done afterwards. Clients that do this must be prepared to handle asynchronous message delivery while they are still in the process of setting up.

A message producer can send messages while a connection is stopped.

Version:

1.1 - February 1, 2002

Author:

Mark Hapner, Rich Burridge, Kate Stout

See Also:

ConnectionFactory, QueueConnection, TopicConnection

public Session createSession(boolean transacted, int acknowledgeMode) throws JMSException
创建 Session 对象。

transacted	指示会话是否是事务性的
acknowledgeMode	指示使用方或客户端是否将确认收到的任何消息；如果会话是事务性的，则忽略此参数。合法值有 Session.AUTO_ACKNOWLEDGE、Session.CLIENT_ACKNOWLEDGE 和 Session.DUPS_OK_ACKNOWLEDGE。
return	新建的会话
Throws	JMSException: 如果 Connection 对象由于某个内部错误或缺少对特定事务和确认模式的支持无法创建会话。
since	1.1
See also	AUTO_ACKNOWLEDGE, CLIENT_ACKNOWLEDGE, DUPS_OK_ACKNOWLEDGE

英文文档：

createSession

Session createSession(boolean transacted,
                      int acknowledgeMode)
                      throws JMSException

Creates a Session object.

Parameters:

transacted - indicates whether the session is transacted

acknowledgeMode - indicates whether the consumer or the client will acknowledge any messages it receives; ignored if the session is transacted. Legal values are Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, and Session.DUPS_OK_ACKNOWLEDGE.

Returns:

a newly created session

Throws:

JMSException - if the Connection object fails to create a session due to some internal error or lack of support for the specific transaction and acknowledgement mode.

Since:

1.1

See Also:

Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, Session.DUPS_OK_ACKNOWLEDGE

public String getClientID() throws JMSException
获取此连接的客户端标识符。

此值特定于 JMS 提供者。它可以由管理员在 ConnectionFactory 对象中预配置，也可以由应用程序通过调用 setClientID 方法动态分配。

return	唯一客户端标识符
Throws	JMSException: 如果 JMS 提供者由于某个内部错误无法返回此连接的客户端 ID。

英文文档：

getClientID

String getClientID()
                   throws JMSException

Gets the client identifier for this connection.

This value is specific to the JMS provider. It is either preconfigured by an administrator in a ConnectionFactory object or assigned dynamically by the application by calling the setClientID method.

Returns:

the unique client identifier

Throws:

JMSException - if the JMS provider fails to return the client ID for this connection due to some internal error.

public void setClientID(String clientID) throws JMSException
设置此连接的客户端标识符。

分配 JMS 客户端的客户端标识符的首选方法是在特定于客户端的 ConnectionFactory 对象中配置它并以透明方式分配给其创建的 Connection 对象。

此外，客户端可以使用特定于提供者的值设置连接的客户端标识符。显式设置连接的客户端标识符的工具不是一种用来重写以管理方式配置的标识符的机制。它是为不存在以管理方式指定的标识符的情况提供的。如果存在以管理方式指定的标识符，则尝试通过设置更改它必定抛出 IllegalStateException。如果客户端要显式地设置客户端标识符，那么它必须在创建连接之后和对连接执行任何其他操作之前立即这样做。在这个时间点之后，设置客户端标识符将成为编程错误，会抛出 IllegalStateException。

客户端标识符的作用是将连接及其对象与提供者代表客户端维持的状态相关联。只有 JMS API 标识的这种状态才是支持持久订阅所需要的。

如果调用此方法时具有相同 clientID 的另一个连接已经在运行，则 JMS 提供者应能检测到重复的 ID 并抛出 InvalidClientIDException。

clientID	唯一客户端标识符
Throws	JMSException: 如果 JMS 提供者由于某个内部错误无法设置此连接的客户端 ID。
Throws	InvalidClientIDException: 如果 JMS 客户端指定了无效或重复的客户端 ID。
Throws	IllegalStateException: 如果 JMS 客户端尝试在错误时间或者在已通过管理方式进行了配置时设置连接的客户端 ID。

英文文档：

setClientID

void setClientID(String clientID)
                 throws JMSException

Sets the client identifier for this connection.

The preferred way to assign a JMS client's client identifier is for it to be configured in a client-specific ConnectionFactory object and transparently assigned to the Connection object it creates.

Alternatively, a client can set a connection's client identifier using a provider-specific value. The facility to set a connection's client identifier explicitly is not a mechanism for overriding the identifier that has been administratively configured. It is provided for the case where no administratively specified identifier exists. If one does exist, an attempt to change it by setting it must throw an IllegalStateException. If a client sets the client identifier explicitly, it must do so immediately after it creates the connection and before any other action on the connection is taken. After this point, setting the client identifier is a programming error that should throw an IllegalStateException.

The purpose of the client identifier is to associate a connection and its objects with a state maintained on behalf of the client by a provider. The only such state identified by the JMS API is that required to support durable subscriptions.

If another connection with the same clientID is already running when this method is called, the JMS provider should detect the duplicate ID and throw an InvalidClientIDException.

Parameters:

clientID - the unique client identifier

Throws:

JMSException - if the JMS provider fails to set the client ID for this connection due to some internal error.

InvalidClientIDException - if the JMS client specifies an invalid or duplicate client ID.

IllegalStateException - if the JMS client attempts to set a connection's client ID at the wrong time or when it has been administratively configured.

public ConnectionMetaData getMetaData() throws JMSException
获取此连接的元数据。

return	连接元数据
Throws	JMSException: 如果 JMS 提供者无法获取此连接的连接元数据。
See also	javax.jms.ConnectionMetaData

英文文档：

getMetaData

ConnectionMetaData getMetaData()
                               throws JMSException

Gets the metadata for this connection.

Returns:

the connection metadata

Throws:

JMSException - if the JMS provider fails to get the connection metadata for this connection.

See Also:

ConnectionMetaData

public ExceptionListener getExceptionListener() throws JMSException
获取此连接的 ExceptionListener 对象。不是每个 Connection 都有与之关联的 ExceptionListener。

return	此连接的 ExceptionListener；如果没有与此连接关联的 ExceptionListener，则返回 null。
Throws	JMSException: 如果 JMS 提供者无法获取此连接的 ExceptionListener。
See also	setExceptionListener

英文文档：

getExceptionListener

ExceptionListener getExceptionListener()
                                       throws JMSException

Gets the ExceptionListener object for this connection. Not every Connection has an ExceptionListener associated with it.

Returns:

the ExceptionListener for this connection, or null. if no ExceptionListener is associated with this connection.

Throws:

JMSException - if the JMS provider fails to get the ExceptionListener for this connection.

See Also:

setExceptionListener(javax.jms.ExceptionListener)

public void setExceptionListener(ExceptionListener listener) throws JMSException
设置此连接的异常侦听器。

如果 JMS 提供者检测到连接存在严重问题，它会通知连接的 ExceptionListener（如果已注册了一个异常侦听器）。这是通过调用侦听器的 onException 方法并将其传递到描述该问题的 JMSException 对象来实现的。

异常侦听器允许客户端异步获得问题的通知。某些连接只使用消息，因此它们没有其他方式来了解其连接已失败。

连接序列化其 ExceptionListener 的执行。

JMS 提供者应该在通知客户端之前尝试自己解决连接问题。

listener	异常侦听器
Throws	JMSException: 如果 JMS 提供者无法设置此连接的异常侦听器。

英文文档：

setExceptionListener

void setExceptionListener(ExceptionListener listener)
                          throws JMSException

Sets an exception listener for this connection.

If a JMS provider detects a serious problem with a connection, it informs the connection's ExceptionListener, if one has been registered. It does this by calling the listener's onException method, passing it a JMSException object describing the problem.

An exception listener allows a client to be notified of a problem asynchronously. Some connections only consume messages, so they would have no other way to learn their connection has failed.

A connection serializes execution of its ExceptionListener.

A JMS provider should attempt to resolve connection problems itself before it notifies the client of them.

Parameters:

listener - the exception listener

Throws:

JMSException - if the JMS provider fails to set the exception listener for this connection.

public void start() throws JMSException
启动或（重启）连接的传入消息传送。对已经启动的连接调用 start 将被忽略。

Throws	JMSException: 如果 JMS 提供者由于某个内部错误无法启动消息传送。
See also	stop

英文文档：

start

void start()
           throws JMSException

Starts (or restarts) a connection's delivery of incoming messages. A call to start on a connection that has already been started is ignored.

Throws:

JMSException - if the JMS provider fails to start message delivery due to some internal error.

See Also:

stop()

public void stop() throws JMSException
暂时停止连接的传入消息传送。可以使用连接的 start 方法重启传送。当连接停止时，对所有连接的消息使用方的传送都被禁止：同步接收阻塞，并且消息没有传送到消息侦听器。

此调用将会一直阻塞，直到正在执行的接收和/或消息侦听器完成为止。

停止连接不会影响其发送消息的能力。对已经停止的连接调用 stop 将被忽略。

在消息传送暂停之前，不能返回对 stop 的调用。这意味着客户端可以确认以下事实：在重启连接之前，不会调用其任何消息侦听器并且等待 receive 调用返回的所有控制线程都不会返回消息。停止连接的接收计时器继续计时，因此当连接停止时，接收可能超时。

如果调用 stop 时消息侦听器正在运行，则 stop 调用必须等到所有消息侦听器返回后，它才能返回。当这些消息侦听器将要完成时，它们必须可以使用连接的全部服务。

Throws	JMSException: 如果 JMS 提供者由于某个内部错误无法停止消息传送。
See also	start

英文文档：

stop

void stop()
          throws JMSException

Temporarily stops a connection's delivery of incoming messages. Delivery can be restarted using the connection's start method. When the connection is stopped, delivery to all the connection's message consumers is inhibited: synchronous receives block, and messages are not delivered to message listeners.

This call blocks until receives and/or message listeners in progress have completed.

Stopping a connection has no effect on its ability to send messages. A call to stop on a connection that has already been stopped is ignored.

A call to stop must not return until delivery of messages has paused. This means that a client can rely on the fact that none of its message listeners will be called and that all threads of control waiting for receive calls to return will not return with a message until the connection is restarted. The receive timers for a stopped connection continue to advance, so receives may time out while the connection is stopped.

If message listeners are running when stop is invoked, the stop call must wait until all of them have returned before it may return. While these message listeners are completing, they must have the full services of the connection available to them.

Throws:

JMSException - if the JMS provider fails to stop message delivery due to some internal error.

See Also:

start()

public void close() throws JMSException
关闭连接。

由于提供者通常会代表连接分配 JVM 之外的重要资源，因此不需要这些资源时客户端应该关闭它们。依赖于垃圾收集最终回收这些资源可能不够及时。

无需关闭已关闭连接的会话、生成方和使用方。

关闭连接会导致所有临时目的地被删除。

调用此方法时，在依次关闭消息处理之前，它不会返回。这意味着可能一直在运行的所有消息侦听器都已经返回，并且所有挂起的接收都已经返回。关闭会终止连接会话的使用方上所有挂起的消息接收。接收可能返回消息或 null，这取决于在关闭时是否有可用的消息。如果调用连接 close 时一个或多个连接会话的消息侦听器正在处理消息，则连接及其会话的所有工具都必须对这些侦听器保持可用，直到它们将控制返回给 JMS 提供者为止。

关闭连接会导致其正在执行的任何会话事务回滚。如果外部事务管理器协调会话的工作，则不使用会话的 commit 和 rollback 方法，并且关闭会话的工作结果将由该事务管理器以后决定。 关闭连接不会强制对客户端确认的会话进行确认。

从已关闭连接的会话调用所接收消息的 acknowledge 方法必须抛出 IllegalStateException。关闭已关闭的连接不会抛出异常。

Throws

JMSException: 如果 JMS 提供者由于某个内部错误无法关闭连接。例如，无法释放资源或关闭套接字会导致抛出此异常。

英文文档：

close

void close()
           throws JMSException

Closes the connection.

Since a provider typically allocates significant resources outside the JVM on behalf of a connection, clients should close these resources when they are not needed. Relying on garbage collection to eventually reclaim these resources may not be timely enough.

There is no need to close the sessions, producers, and consumers of a closed connection.

Closing a connection causes all temporary destinations to be deleted.

When this method is invoked, it should not return until message processing has been shut down in an orderly fashion. This means that all message listeners that may have been running have returned, and that all pending receives have returned. A close terminates all pending message receives on the connection's sessions' consumers. The receives may return with a message or with null, depending on whether there was a message available at the time of the close. If one or more of the connection's sessions' message listeners is processing a message at the time when connection close is invoked, all the facilities of the connection and its sessions must remain available to those listeners until they return control to the JMS provider.

Closing a connection causes any of its sessions' transactions in progress to be rolled back. In the case where a session's work is coordinated by an external transaction manager, a session's commit and rollback methods are not used and the result of a closed session's work is determined later by the transaction manager. Closing a connection does NOT force an acknowledgment of client-acknowledged sessions.

Invoking the acknowledge method of a received message from a closed connection's session must throw an IllegalStateException. Closing a closed connection must NOT throw an exception.

Throws:

JMSException - if the JMS provider fails to close the connection due to some internal error. For example, a failure to release resources or to close a socket connection can cause this exception to be thrown.

public ConnectionConsumer createConnectionConsumer(Destination destination, String messageSelector, ServerSessionPool sessionPool, int maxMessages) throws JMSException
创建此连接的连接使用方（可选操作）。这是一个专家级工具，常规 JMS 客户端不使用。

destination	要访问的目的地
messageSelector	仅包括那些属性匹配所传送的消息选择器表达式的消息。值为 null 或空字符串表示该消息使用方没有消息选择器。
sessionPool	与此连接使用方关联的服务器会话池
maxMessages	可以一次分配给服务器会话的最大消息数
return	连接使用方
Throws	JMSException: 如果 Connection 对象由于某个内部错误或 sessionPool 和 messageSelector 的无效参数无法创建连接使用方。
Throws	InvalidDestinationException: 如果指定了无效的目的地。
Throws	InvalidSelectorException: 如果消息选择器无效。
since	1.1
See also	javax.jms.ConnectionConsumer

英文文档：

createConnectionConsumer

ConnectionConsumer createConnectionConsumer(Destination destination,
                                            String messageSelector,
                                            ServerSessionPool sessionPool,
                                            int maxMessages)
                                            throws JMSException

Creates a connection consumer for this connection (optional operation). This is an expert facility not used by regular JMS clients.

Parameters:

destination - the destination to access

messageSelector - only messages with properties matching the message selector expression are delivered. A value of null or an empty string indicates that there is no message selector for the message consumer.

sessionPool - the server session pool to associate with this connection consumer

maxMessages - the maximum number of messages that can be assigned to a server session at one time

Returns:

the connection consumer

Throws:

JMSException - if the Connection object fails to create a connection consumer due to some internal error or invalid arguments for sessionPool and messageSelector.

InvalidDestinationException - if an invalid destination is specified.

InvalidSelectorException - if the message selector is invalid.

Since:

1.1

See Also:

ConnectionConsumer

public ConnectionConsumer createDurableConnectionConsumer(Topic topic, String subscriptionName, String messageSelector, ServerSessionPool sessionPool, int maxMessages) throws JMSException
创建此连接的持久连接使用方（可选操作）。这是一个专家级工具，常规 JMS 客户端不使用。

topic	要访问的主题
subscriptionName	持久订阅名称
messageSelector	仅包括那些属性匹配所传送的消息选择器表达式的消息。值为 null 或空字符串表示该消息使用方没有消息选择器。
sessionPool	关联此持久连接使用方的服务器会话池
maxMessages	可以一次分配给服务器会话的最大消息数
return	持久连接使用方
Throws	JMSException: 如果 Connection 对象由于某个内部错误或 sessionPool 和 messageSelector 的无效参数无法创建连接使用方。
Throws	InvalidDestinationException: 如果指定了无效的目的地。
Throws	InvalidSelectorException: 如果消息选择器无效。
since	1.1
See also	javax.jms.ConnectionConsumer

英文文档：

createDurableConnectionConsumer

ConnectionConsumer createDurableConnectionConsumer(Topic topic,
                                                   String subscriptionName,
                                                   String messageSelector,
                                                   ServerSessionPool sessionPool,
                                                   int maxMessages)
                                                   throws JMSException

Create a durable connection consumer for this connection (optional operation). This is an expert facility not used by regular JMS clients.

Parameters:

topic - topic to access

subscriptionName - durable subscription name

messageSelector - only messages with properties matching the message selector expression are delivered. A value of null or an empty string indicates that there is no message selector for the message consumer.

sessionPool - the server session pool to associate with this durable connection consumer

maxMessages - the maximum number of messages that can be assigned to a server session at one time

Returns:

the durable connection consumer

Throws:

JMSException - if the Connection object fails to create a connection consumer due to some internal error or invalid arguments for sessionPool and messageSelector.

InvalidDestinationException - if an invalid destination is specified.

InvalidSelectorException - if the message selector is invalid.

Since:

1.1

See Also:

ConnectionConsumer

Copyright 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.