1. Administering JMS Resources for Oracle WebLogic Server
  2. JMS Resource Definition Elements Reference

A JMS Resource Definition Elements Reference

Oracle WebLogic Server lets you configure JMS resources using the elements for destinations and connections factories. These JMS resource definitions allow an application to be deployed into a Jakarta EE environment with minimal administrative configuration.

Note:

Oracle generally recommends using system modules instead of definitions to define JMS resources. System module configured resources can be added, removed, and modified without requiring a change, rebuild, and redeploy of an application. See Configure a JMS System Module.

The following sections describe the Jakarta Messaging resource definition elements and properties:

Defining JMS Resources Using Jakarta EE Resource Definitions

You can define the JMS resources using the @JMSConnectionFactoryDefinition and @JMSDestinationDefinition annotations, or the <jms-destination> and <jms-connection-factory> elements as defined in the Java EE 7 Platform Specification.These JMS resource definitions allow an application to be deployed into a Jakarta EE environment with minimal administrative configuration.

Note:

JMS resources that are configured within the scope of an application cannot be modified after the application is deployed. In addition, there is no direct option to delete destinations that are created in the application module. Undeploying the application does not delete the destination. For these reasons, it is recommended that you configure connection factories and destinations using a JMS system module instead. See JMS System Module Configuration.

Parent topic: JMS Resource Definition Elements Reference

Resource Definitions Using Annotations

You can define the annotations @JMSConnectionFactoryDefinition and @JMSDestinationDefinitions inside the web module, EJB module, or an application client module. You can also define resources using the annotations inside these classes:

  • Classes defined in the libraries defined by the <library-directory> element of the application.xml deployment descriptor

  • Classes in a .jar file referenced by the Class-path entry of a EJB jar file or a .war file

After it is defined, a resource can be referenced by a component using the lookup element of the @Resource annotation or using the look-up element of the resource-ref deployment descriptor element..

Example A-1 Example: JMS Connection Factory Definition

@JMSConnectionFactoryDefinition(   name="java:app/MyJMSConnectionFactory",   interfaceName="javax.jms.QueueConnectionFactory").

Example A-2 Example: JMS Destination Definition

@JMSDestinationDefinition(   name="java:app/MyJMSQueue",   interfaceName="javax.jms.Queue",   destinationName="myQueue1")

For more information about the elements and properties that you can use with the resource definitions, see JMS Resource Definition Elements Reference

Parent topic: Defining JMS Resources Using Jakarta EE Resource Definitions

Resource Definitions in the Deployment Descriptor

Instead of using annotations, you can define resources using the <jms-destination> and <jms-connection-factory> elements in the deployment descriptor.

JMS Connection Factory Definition

You can define a JMS destination resource using the jms-connection-factory element in the ejb-jar.xml or web.xml deployment descriptors. It creates the connection factory and binds it to the appropriate naming context based on the namespace specified.

The following example defines a connection factory that is bound to JNDI at the location java:app/MyJMSConnectionFactory: 

<jms-connection-factory>   <description>Sample JMS ConnectionFactory definition</description>   <name>java:app/MyJMSConnectionFactory</name>   <interface-name>javax.jms.QueueConnectionFactory</interface-name>   <user>scott</user>   <password>tiger</password>   <client-id>MyClientId</client-id>   <property>     <name>Property1</name>     <value>10</value>  </property>   <property>     <name>Property2</name>     <value>20</value>   </property>   <transactional>false</transactional>   <max-pool-size>30</max-pool-size>   <min-pool-size>20</min-pool-size> </jms-connection-factory>

For more information about the jms-connection-factory element and its attributes, see the schema at http://www.oracle.com/webfolder/technetwork/jsc/xml/ns/javaee/javaee_8.xsd

JMS Destination Definition

You can define a JMS destination resource using the jms-destination element in the ejb-jar.xml or web.xml deployment descriptors. It creates the destination and binds it to the appropriate naming context based on the namespace specified.

The following example defines a queue destination myQueue1 that is bound to JNDI at the location java:app/MyJMSDestination:

<jms-destination>   <description>JMS Destination definition</description>   <name>java:app/MyJMSDestination</name>   <interface-name>javax.jms.Queue</interface-name>   <destination-name>myQueue1</destination-name>   <property>     <name>Property1</name>     <value>10</value>   </property>   <property>     <name>Property2</name>     <value>20</value>   </property> </jms-destination>

For more information about the jms-destination element and its attributes, see the schema at http://www.oracle.com/webfolder/technetwork/jsc/xml/ns/javaee/javaee_8.xsd

Parent topic: Defining JMS Resources Using Jakarta EE Resource Definitions

Considerations and Best Practices for Using JMS Resource Definitions

The following are the considerations for resources that are defined using the new annotations:

  • Define a JMS resource in any of the following allowed JNDI namespaces:

    • java:comp

    • java:module

    • java:app

    • java:global

  • When the JNDI name starts with java: but does not start with any of the prior namespace prefixes, that results in an exception during deployment.

  • When the JNDI name does not start with java:, the destination or the connection factory is defined in the java:comp/env namespace. For example, a JNDI name of the format jms/myDestination is considered to be the same as java:comp/env/jms/myDestination.

  • WebLogic Server allows an application to define a destination in java:app and java:global namespaces in the application.xml deployment descriptor or by using an annotation on a class in the application package other than a class within a web module, an EJB module, or an application client module.

  • The destination defined using @JMSDestinationDefinition is internally created as uniform distributed destinations (queues or topics). By default, the value of the Forwarding Policy option for a uniform distributed topic that is created using @JMSDestinationDefinition with interfaceName of type javax.jms.Topic is 'Partitioned'. You can specify the value as 'Replicated' in the application deployment. See Best Practices for Distributed Topics in Developing JMS Applications for Oracle WebLogic Server.

  • When an application that defines a queue using @JMSDestinationDefinition is undeployed, the persistent store preserves the messages that are not received or consumed, and those messages are available for consumers of the destination when you redeploy the application.

For more information, see Annotation Type JMSConnectionFactoryDefinition and Annotation Type JMSDestinationDefinition in Java(TM) EE7 Specification APIs..

Parent topic: Defining JMS Resources Using Jakarta EE Resource Definitions

JMS Connection Factory Definition Elements and Properties

You can configure the connection factory in an application module using a JMS resource definition.

This section explains the elements of the resource definition as mentioned in Java(TM) EE7 Specification APIs document. See Annotation Type JMSConnectionFactoryDefinition.

The following example defines a connection factory using the @JMSConnectionFactoryDefinition annotation: 

@JMSConnectionFactoryDefinition(
    name="java:global/jms/demoConnectionFactory",
    className= "javax.jms.ConnectionFactory",
    description="Sample description for Connection Factory",
    clientId="client_Id01",
    transactional=true,
    properties= {"UserName=myuser", "delivery-mode=Persistent", "load-balancing-enabled=true"}

For the element definitions in the JMS application module, see the weblogic-jms.xsd schema available at http://xmlns.oracle.com/weblogic/weblogic-jms/1.8/weblogic-jms.xsd .

Table A-1 @JMSConnectionFactoryDefinition Elements

Element in @JMSConnectionFactoryDefinition Elements Equivalent Element in the JMS Application Module Type Description
name jndi-name

String

The JNDI name of the JMS connection factory that is being defined.

NOTE: This is a mandatory element.
description notes

String

A description of the connection factory.
clientId clientId

String

The client ID to be used for the connection.
transactional transaction-paramsxa-connection-factory-enabled

Boolean

Specifies whether the connections participate in transactions. Set this property to

false

if connections should not participate in transactions.

. The default is True.
resourceAdapter

None

String

The name of the resource adapter.
className

None

String

The value is ignored.
InterfaceName

None

String

The value is ignored.
maxPoolSize

None

integer

The value is ignored.
minPoolSize

None

integer

The value is ignored.
user

None

String

The value is ignored.
password

None

String

The value is ignored.

JMS Connection Factory Properties

Note:

The properties defined in this section apply only when the connection factory definition does not specify an adapter. When an adapter is specified, properties that are unique to the adapter are considered.

Table A-2 @JMSConnectionFactoryDefinition Properties

@JMSConnectionFactoryDefinition Property Equivalent Element in the JMS Application Module Type Description
name name

Sting

A name for the connection factory. When not specified, the name is <module_name>_cf, where <module_name>represents the name of the JMS application module where the resource is defined.

jms-server-name sub-deployment-name

Sting

The JMS server to which the resource is targeted. If the jms-server-name specified by the application does not exist in the scope of the deployment, then the deployment fails with an exception indicating the reason for the failure.

default-targeting-enabled default-targeting-enabled

boolean

Set this property to true when jms-server-name is not specified. This value is ignored when jms-server-name is specified.

Table A-3 @JMSConnectionFactoryDefinition Properties for Default Message Delivery

@JMSConnectionFactoryDefinition Property Equivalent default-delivery-params Element in the JMS Application Module Type Description
default-delivery-mode default-delivery-mode

String

The delivery mode assigned to all messages sent by a producer using the connection factory that is being defined. Accepted values: Persistent or Non-persistent
default-time-to-deliver default-time-to-deliver

String

The delay time, in milliseconds, between when a message is produced and when it is made visible on its destination
default-time-to-live default-time-to-live

Long

The maximum length of time, in milliseconds, that a message exists. This value is used for messages when a priority is not explicitly defined.
default-priority default-priority

integer

The default priority used for messages when a priority is not explicitly defined.

default-redelivery-delay default-redelivery-delay

Long

The delay time, in milliseconds, before rolled back or recovered messages are redelivered.
default-compression-threshold default-compression-threshold

integer

The number of bytes for a serialized message body so any message that exceeds this limit triggers message compression when the message is sent or received by the JMS message producer or consumer
default-unit-of-order default-unit-of-order

String

The default Unit-of-Order producer for this connection factory.

Options are: System-generated and User-Generated.
send-timeoutr send-timeoutr

Long

The maximum length of time, in milliseconds, that a sender waits when there is not enough available space (no quota) on a destination to accommodate the message being sent.

Table A-4 @JMSConnectionFactoryDefinition Client Properties

@JMSConnectionFactoryDefinition Property Equivalent client-params element in the JMS Application Module Type Description
client-id-policy client-id-policy

String

Whether more than one JMS connection can use the same client ID. Valid options are Restricted and Unrestricted.

subscription-sharing-policy subscription-sharing-policy

String

The Subscription Sharing Policy on the connection.

Valid options are Exclusive and Sharable.

acknowledge-policy acknowledge-policy

String

The client acknowledge policy for non transacted sessions that use the CLIENT_ACKNOWLEDGE mode.Valid options are All and Previous.

allow-close-in-onMessage allow-close-in-onMessage

Boolean

Whether the connection factory creates message consumers that allow a close() method to be issued within its onMessage() method call.

NOTE: The default value of this property is false for a connection factory that is created by using the JMS Connection Factory Definition. If connection factory is created in a JMS system module or in a application-scoped module, the default value of allow-close-in-onMessage will be true.
messages-maximum messages-maximum

int

The maximum number of messages that can exist for an asynchronous session and that have not yet been passed to the message listener
multicast-overrun-policy multicast-overrun-policy

String

The policy to be used when the number of outstanding multicast messages reaches the value specified in messages-maximum and some messages must be deleted.

Valid options are KeepOld and KeepNew.

synchronous-prefetch-mode synchronous-prefetch-mode

String

Whether a synchronous consumer will prefetch messages (that is, messages sent from the server to the client) in one server access.

Valid options are enabled, disabled or topicSubscriberOnly..

reconnect-policy reconnect-policy

String

Which types of JMS clients are explicitly and implicitly refreshed after a lost network connection with a server or upon a server restart.

Valid options are none, producer or all.

reconnect-blocking-millis reconnect-blocking-millis

Long

The maximum length of time, in milliseconds, that any synchronous JMS calls block the calling thread before giving up on a JMS client reconnect in progress.
total-reconnect-period-millis total-reconnect-period-millis

Long

The maximum length of time, in milliseconds, that JMS clients (particularly asynchronous consumers) continue to try to reconnect to the server after either the initial network disconnect or the last synchronous call attempt, whichever occurred most recently, before giving up retrying.

Table A-5 @JMSConnectionFactoryDefinition Transaction Properties

@JMSConnectionFactoryDefinition Property Equivalent transaction-params element in the JMS Application Module Type Description
transaction-timeout transaction-timeout

Long

The timeout value (in seconds) for all transactions on connections created with the connection factory.

Set this property only when the transactional element is set to true.

Table A-6 @JMSConnectionFactoryDefinition Flow Control Properties

@JMSConnectionFactoryDefinition Property Equivalent flow-control-params Element in the JMS Application Module Type Description
flow-minimum flow-minimum

integer

The maximum number of messages-per-second allowed for a producer that is experiencing a threshold condition. When a producer is flow controlled it is never be allowed to go faster than the FlowMaximum messages per second.
flow-maximum flow-maximum

integer

The minimum number of messages-per-second allowed for a producer that is experiencing a threshold condition. This is the lower boundary of a producer's flow limit. That is, WebLogic JMS does not further slow down a producer whose message flow limit is at its FlowMinimum.
flow-interval flow-interval

integer

The adjustment period of time, in seconds, when a producer adjusts its flow from the FlowMaximum number of messages to the FlowMinimum amount, or reverse.
flow-steps flow-steps

integer

The number of steps used when a producer is adjusting its flow from the Flow Maximum amount of messages to the Flow Minimum amount, or vice versa.
flow-control-enabled flow-control-enabled

Boolean

Whether a producer created using a connection factory allows flow control.
one-way-send-mode one-way-send-mode

String

Whether message producers created using this connection factory are allowed to do one-way message sends to improve typical non-persistent, non-transactional messaging performance.

Valid options are enabled, disabled, or topicOnly.

one-way-send-window-size one-way-send-window-size

integer

The maximum number of sent messages per window when One-Way Send Mode is set to allow queue senders and/or topic publishers to make one-way sends. The window size determines when a two-way message is required to regulate the producer before it can continue making additional one-way sends.

Table A-7 @JMSConnectionFactoryDefinition Load Balancing Properties

@JMSConnectionFactoryDefinition Property Equivalent load-balancing-params Element in the JMS Application Module Type Description
load-balancing-enabled load-balancing-enabled

Boolean

Whether non-anonymous producers created through a connection factory are load balanced within a distributed destination on a per-call basis.
server-affinity-enabled server-affinity-enabled

Boolean

Whether a server instance that is load balancing consumers or producers across multiple members destinations of a distributed destination, first attempts to load balance across any other physical destinations that are also running on the same server instance.

Table A-8 @JMSConnectionFactoryDefinition Load Balancing Properties

@JMSConnectionFactoryDefinition Property Equivalent security-params Element in the JMS Application Module Type Description
attach-jmsx-user-id attach-jmsx-user-id

Boolean

Whether non-anonymous producers created through a connection factory are load balanced within a distributed destination on a per-call basis.

Parent topic: JMS Resource Definition Elements Reference

JMS Destination Definition Elements and Properties

You can configure a JMS destination resource in an application module by using a JMS resource definition.

This section describes the elements of the resource definition as mentioned in Defining JMS Resources Using Jakarta EE Resource Definitions.

The following example defines a destination using the @JMSDestinationDefinition annotation: 

@JMSDestinationDefinition(
name="java:global/jms/demoDestination",
interfaceName="javax.jms.Queue",   
className= "javax.jms.Queue",
description="Sample description for Queue",
destinationName="myQueue",
properties= {"default-unit-of-order=true", "time-to-deliver=Persistent", "attach-sender=always"}

For more information, see Annotation Type JMSDestinationDefinition.

For the element definitions in the JMS application module, see the http://xmlns.oracle.com/weblogic/weblogic-jms/1.8/weblogic-jms.xsd

Table A-9 @JMSDestinationDefinition Elements

Element in @JMSDestinationDefinition Equivalent Element in the JMS Application Module Type Description
name jndi-name

String

The JNDI name of the JMS destination resource that is being defined.

NOTE: This is a mandatory element.
interfaceName uniform-distributed-queue or uniform-distributed-topic.

String

The fully qualified name of the JMS destination interface. Valid options are javax.jms.Queue or javax.jms.Topic.

The JMS destination definition is converted to a JMS module with entity of type uniform-distributed-queue or uniform-distributed-topic based on the value specified for interfaceName.

NOTE: This is a mandatory element.
description notes

String

A description for the JMS destination that is being defined.
destination name name

String

The runtime MBean name of the queue or topic. When not specified, the destination name is <module_name>_<queue/topic>, where <module_name> represents the name of the JMS application module where the resource is defined.

className

None

 -

This value is ignored.
resourceAdapter

None

 -

This value is ignored.

Table A-10 @JMSDestinationDefinition Properties

@JMSDestinationDefinition Property Equivalent Element in the JMS Application Module Type Description
jms-server-name sub-deployment-name

String

The JMS server to which the resource is targeted. If the jms-server-name specified by the application does not exist in the scope of the deployment, then the deployment will fail with an exception indicating the reason for the failure.

default-targeting-enabled default-targeting-enabled

Boolean

Set this property to true when jms-server-name is not specified.

This value is ignored when jms-server-name is specified.

Table A-11 @JMSDestinationDefiition Threshold Properties

@JMSDestinationDefinition Property Equivalent thresholds Element in the JMS Applicaton Module Type Description
bytes-high bytes-high

Long

The upper threshold (total number of bytes in this destination) that triggers logging or flow control events.
bytes-low bytes-low

Long

The lower threshold (total number of bytes in this destination) that triggers logging or flow control events.
messages-high messages-high

Long

The upper threshold (total number of messages in this destination) that triggers logging or flow control events.
messages-low messages-low

Long

The lower threshold (total number of messages in this destination) that triggers logging or flow control events.

Table A-12 @JMSDestinationDefinition Message Delivery Override Properties

@JMSDestinationDefinition Property Equivalent delivery-params-overrides Element in the JMS Application Module Type Description
delivery-mode delivery-mode

String

The delivery mode assigned to all messages that arrive at the destination regardless of the DeliveryMode specified by the message producer.

Valid options are Persistent or Non-Persistent.
time-to-deliver time-to-deliver

String

The delivery delay, either in milliseconds or as a schedule, between when a message is produced and when it is made visible on its target distributed destination.
time-to-live time-to-live

Long

The time-to-live assigned to all messages that arrive at the destination, regardless of the TimeToLive value specified by the message producer.
priority priority

Integer

The priority assigned to all messages that arrive at the destination, regardless of the Priority specified by the message producer.
redelivery-delay redelivery-delay

Long

The delay, in milliseconds, before rolled back or recovered messages are redelivered, regardless of the RedeliveryDelay specified by the consumer and/or connection factory.

Table A-13 @JMSDestinationDefinition Message Delivery Failure Properties

@JMSDestinationDefinition Property Equivalent delivery-failure params Element in the JMS Application Module Type Description
redelivery-limit redelivery-limit

Integer

The number of redelivery tries a message can have before it is moved to the error destination.
expiration-policy expiration-policy

String

The message Expiration Policy to be used when an expired message is encountered on a destination.

Valid options are Discard or Log or Redirect.

expiration-logging-policy expiration-logging-policy

String

The information about the message is logged when the Expiration Policy is set to Log.

Table A-14 @JMSDestinationDefinition Message Logging Properties

@JMSDestinationDefinition Property Equivalent message-logging-params Element in the JMS Application Module Type Description
message-logging-enabled message-logging-enabled

Boolean

Whether the module logs information about the message life cycle.
message-logging-format message-logging-format

String

The information about the message is logged.

This property is defined as shown in the following example:

For more information about the valid values for this property, see the description for the MessageLoggingFormat attribute of MessageLoggingParamsBean in MBean Reference for Oracle WebLogic Server.

Table A-15 @JMSDestinationDefinition Advanced Configuration Properties

@JMSDestinationDefinition Property Equivalent Element in the JMS Application Module Type Description
load-balancing-policy load-balancing-policy

String

How messages are distributed to the members of this destination

Valid options are Round-Robin and Random
production-paused-at-startup production-paused-at-startup

Boolean

Whether new message production is paused on a destination at startup
insertion-paused-at-startup insertion-paused-at-startup

Boolean

Whether new message insertion is paused on a destination at startup.
consumption-paused-at-startup consumption-paused-at-startup

Boolean

Whether consumption is paused on a destination at startup.
default-unit-of-order default-unit-of-order

Boolean

Specifies whether WebLogic Server creates a system-generated unit-of-order name based on the domain, JMS server, and destination name.
unit-of-order-routing unit-of-order-routing

String

Determines how a distributed destination member is selected as the destination for a message that is part of a unit-of-order.

Valid options are Hash and PathService.

attach-sender attach-sender

String

Whether messages landing on this destination should attach the credential of the sending user. Valid options are supports, always, and never.

jms-create-destination-identifier jms-create-destination-identifier

String

A reference name for a destination or a member of a distributed destination that provides a way to look-up that destination without JNDI using javax.jms.Session createQueue or createTopic.
saf-export-policy saf-export-policy

String

Whether a user can send messages to a destination using Store-and-Forward. Valid options are All and None.

messaging-performance-preferenc messaging-performance-preferenc

Integer

How long destinations are willing to wait to create full batches of available messages (if at all) for delivery to consumers.
unit-of-work-handling-policy unit-of-work-handling-policy

String

Whether the Unit-of-Work (UOW) feature is enabled for this destination.

Valid options are PassThrough and SingleMessageDelivery.

incomplete-work-expiration-time incomplete-work-expiration-time

Integer

The maximum length of time, in milliseconds, before undelivered messages in an incomplete UOW are expired.

Note:

These properties are applicable only when the interfaceName element of @JMSDestinationDefinition is set to javax.jms.Queue.

Table A-16 @JMSDestinationDefinition Properties for Queue Destinations

@JMSDestinationDefinition Property Equivalent Element in the JMS Application Module Type Description
forward-delay forward-delay

Integer

The number of seconds after which a uniform distributed queue member with no consumers wait before forwarding its messages to other uniform distributed queue members that do have consumers.
reset-delivery-count-on-forward reset-delivery-count-on-forward

Boolean

Whether or not the delivery count is reset during message forwarding between distributed queue members.

Note:

These properties are applicable only when the interfaceName element of @JMSDestinationDefinition is set to javax.jms.Topic.

Table A-17 @JMSDestinationDefinition Properties for Topic Destinations

@JMSDestinationDefinition Property Equivalent Element in the JMS Application Module Type Description
forwarding-policy forwarding-policy

String

The uniform distributed topic message Forwarding Policy specifies whether or not a sent message is forwarded to all members.

Valid options are Partitioned and Replicated.

When a destination is created by using JMS destination definition, the default value of this property is Partitioned. The default value is Replicated if the destination is created otherwise.

multicast-address multicast-address

String

The address used by the topic to transmit messages to multicast consumers.
multicast-time-to-live multicast-time-to-live

Integer

The Time-To-Live value used for multicasting, which specifies the number of routers that the message can traverse en route to the consumers.
multicast-port multicast-port

Integer

The port used by the topic to transmit messages to multicast consumers.

Parent topic: JMS Resource Definition Elements Reference