Content starts here JMS C API Reference for Oracle WebLogic Server
Skip navigation.
Main Page  |  Data Structures  |  File List  |  Data Fields  |  Globals

JmsConnection.h File Reference

Describes a JmsConnection handle. More...

#include <JmsCommon.h>
#include <JmsContext.h>
#include <JmsMetaData.h>
#include <JmsConnectionFactory.h>
#include <JmsSession.h>
#include <JmsTypes.h>

Go to the source code of this file.


Typedefs

typedef JmsConnection JmsConnection

Functions

int JMSENTRY JmsConnectionFactoryCreateConnection (JmsConnectionFactory *connectionFactory, JmsConnection **connection, JMS64I flags)
int JMSENTRY JmsConnectionCreateSession (JmsConnection *connection, int transacted, int acknowledeMode, JmsSession **session, JMS64I flags)
int JMSENTRY JmsConnectionGetClientId (JmsConnection *connection, JmsString *clientId, JMS64I flags)
int JMSENTRY JmsConnectionSetClientId (JmsConnection *connection, JmsString *clientId, JMS64I flags)
int JMSENTRY JmsConnectionGetMetaData (JmsConnection *connection, JmsMetaData **metaData, JMS64I flags)
int JMSENTRY JmsConnectionGetExceptionListener (JmsConnection *connection, void(**listener)(JmsException *, void *, JMS64I), void **argument, JMS64I flags)
int JMSENTRY JmsConnectionSetExceptionListener (JmsConnection *connection, void(*listener)(JmsException *, void *, JMS64I), void *argument, JMS64I flags)
int JMSENTRY JmsConnectionStart (JmsConnection *connection, JMS64I flags)
int JMSENTRY JmsConnectionStop (JmsConnection *connection, JMS64I flags)
int JMSENTRY JmsConnectionClose (JmsConnection *connection, JMS64I flags)

Detailed Description

Describes a JmsConnection handle.

Author:
Copyright (c) 2002, BEA Systems, Inc. This file describes the functions that can be performed on a JmsConnection handle A JmsConnection handle corresponds to javax.jms.Connection

Typedef Documentation

typedef struct JmsConnection JmsConnection
 

A connection handle that represents the class javax.jms.Connection

Function Documentation

int JMSENTRY JmsConnectionClose (  JmsConnection *    connection,
JMS64I    flags
) 
 

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.

Unlike the java close, all sessions, producers, and consumers of a closed connection must be closed explicitly in order to free up their handles.

Closing a connection causes all temporary destinations to be deleted. However, all temporary destinations must be explicitly closed in order to free up their handles.

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.

Parameters:
connection  Must be a valid connection handle. May not be NULL
flags  Reserved for future use. Must be zero
Returns:
  • JMS_NO_ERROR
  • JMS_GOT_EXCEPTION
  • JMS_INPUT_PARAM_ERROR
  • JMS_MALLOC_ERROR
  • JMS_JVM_ERROR

int JMSENTRY JmsConnectionCreateSession (  JmsConnection *    connection,
int    transacted,
int    acknowledeMode,
JmsSession **    session,
JMS64I    flags
) 
 

Gets a session handle from a connection handle

Parameters:
connection  Must be a valid connection handle. May not be NULL
transacted  If not zero, this session will be transacted. If zero, this session will not be transacted
acknowledgeMode  One of the following values
  • AUTO_ACKNOWLEDGE Messages will be automatically acknoweldged
  • CLIENT_ACKNOWLEDGE The user must explicitly acknowledge messages
  • DUPS_OK_ACKNOWLEDGE Messages will be automatically acknowledged, and duplicate messages are allowable
session  May not be NULL. On success *session will contain a valid JmsSession handle
flags  Reserved for future use. Must be zero
Returns:
  • JMS_NO_ERROR
  • JMS_GOT_EXCEPTION
  • JMS_INPUT_PARAM_ERROR
  • JMS_MALLOC_ERROR
  • JMS_JVM_ERROR

int JMSENTRY JmsConnectionFactoryCreateConnection (  JmsConnectionFactory *    connectionFactory,
JmsConnection **    connection,
JMS64I    flags
) 
 

Gets a connection handle from a connection factory handle

Parameters:
connectionFactory  Must be a valid connection factory handle. May not be NULL
connection  May not be NULL. On success *connection will contain a valid JmsConnection handle
flags  Reserved for future use. Must be zero
Returns:
  • JMS_NO_ERROR
  • JMS_GOT_EXCEPTION
  • JMS_INPUT_PARAM_ERROR
  • JMS_MALLOC_ERROR
  • JMS_JVM_ERROR

int JMSENTRY JmsConnectionGetClientId (  JmsConnection *    connection,
JmsString *    clientId,
JMS64I    flags
) 
 

Gets the client identifier associated with this connection handle

Parameters:
connection  Must be a valid connection handle. May not be NULL
clientId  Must not be NULL. On success will contain the client identifier
flags  Reserved for future use. Must be zero
Returns:
  • JMS_NO_ERROR
  • JMS_GOT_EXCEPTION
  • JMS_INPUT_PARAM_ERROR
  • JMS_MALLOC_ERROR
  • JMS_JVM_ERROR

int JMSENTRY JmsConnectionGetExceptionListener (  JmsConnection *    connection,
void(**    listener)(JmsException *, void *, JMS64I),
void **    argument,
JMS64I    flags
) 
 

Gets a the exception listener function associated with this connection

Parameters:
connection  Must be a valid connection handle. May not be NULL
listener  May not be NULL. On success *listener will contain the exception listener function
argument  May not be NULL. On success *argument will contain the application supplied argument used for this connection
flags  Reserved for future use. Must be zero
Returns:
  • JMS_NO_ERROR
  • JMS_GOT_EXCEPTION
  • JMS_INPUT_PARAM_ERROR
  • JMS_MALLOC_ERROR
  • JMS_JVM_ERROR

int JMSENTRY JmsConnectionGetMetaData (  JmsConnection *    connection,
JmsMetaData **    metaData,
JMS64I    flags
) 
 

Gets a meta data handle associated with this connection

Parameters:
connection  Must be a valid connection handle. May not be NULL
metaData  May not be NULL. On success *metaData will contain a valid meta data handle
flags  Reserved for future use. Must be zero
Returns:
  • JMS_NO_ERROR
  • JMS_GOT_EXCEPTION
  • JMS_INPUT_PARAM_ERROR
  • JMS_MALLOC_ERROR
  • JMS_JVM_ERROR

int JMSENTRY JmsConnectionSetClientId (  JmsConnection *    connection,
JmsString *    clientId,
JMS64I    flags
) 
 

Sets the client identifier associated with this connection handle

Parameters:
connection  Must be a valid connection handle. May not be NULL
clientId  Must not be NULL. The client identifier to set on this handle
flags  Reserved for future use. Must be zero
Returns:
  • JMS_NO_ERROR
  • JMS_GOT_EXCEPTION
  • JMS_INPUT_PARAM_ERROR
  • JMS_MALLOC_ERROR
  • JMS_JVM_ERROR

int JMSENTRY JmsConnectionSetExceptionListener (  JmsConnection *    connection,
void(*    listener)(JmsException *, void *, JMS64I),
void *    argument,
JMS64I    flags
) 
 

Sets an exception listener function associated with this connection The exception passed into the listener function is destroyed by the system. Hence the exception should not be freed by the listener function and should not be referenced after the listener function returns

Parameters:
connection  Must be a valid connection handle. May not be NULL
listener  The function that should be called in the event an exception happens on this connection. The exception passed into the function will normally be freed by the system when the function returns (see flags). The second argument to the function is an application defined argument.
argument  The argument to be passed as the second parameter to the exception listener. The application can use this for any reason.
flags  JMS_APPLICATION_MUST_FREE_HANDLE should be set if the exception handle given to the listener function should not be freed by the system when the function returns. The flags value (plus the JMS_CALLED_FROM_JMS flag) will be passed to the listener function as its flags input parameter on every invokation.
Returns:
  • JMS_NO_ERROR
  • JMS_GOT_EXCEPTION
  • JMS_INPUT_PARAM_ERROR
  • JMS_MALLOC_ERROR
  • JMS_JVM_ERROR

int JMSENTRY JmsConnectionStart (  JmsConnection *    connection,
JMS64I    flags
) 
 

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

Parameters:
connection  Must be a valid connection handle. May not be NULL
flags  Reserved for future use. Must be zero
Returns:
  • JMS_NO_ERROR
  • JMS_GOT_EXCEPTION
  • JMS_INPUT_PARAM_ERROR
  • JMS_MALLOC_ERROR
  • JMS_JVM_ERROR

int JMSENTRY JmsConnectionStop (  JmsConnection *    connection,
JMS64I    flags
) 
 

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.

Parameters:
connection  Must be a valid connection handle. May not be NULL
flags  Reserved for future use. Must be zero
Returns:
  • JMS_NO_ERROR
  • JMS_GOT_EXCEPTION
  • JMS_INPUT_PARAM_ERROR
  • JMS_MALLOC_ERROR
  • JMS_JVM_ERROR

Copyright 1996, 2019, Oracle and/or its affiliates. All rights reserved. Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.

Oracle Fusion Middleware
JMS C API Reference for Oracle WebLogic Server
12c (12.2.1.4.0)

Part Number E90603-01

Generated by doxygen 1.2.18