Programming WebLogic JMS

Introduction and Roadmap

Document Scope and Audience

Guide to this Document

Samples and Tutorials for the JMS Developer

Avitek Medical Records Application (MedRec) and Tutorials

JMS Examples in the WebLogic Server Distribution

New and Changed JMS Features In This Release

Understanding WebLogic JMS

Overview of the Java Message Service and WebLogic JMS

What Is the Java Message Service?

Implementation of Java Specifications

Java EE Specification

JMS Specification

WebLogic JMS Architecture

Major Components

Understanding the Messaging Models

Point-to-Point Messaging

Publish/Subscribe Messaging

Message Persistence

Value-Added Public JMS API Extensions

WebLogic Server Value-Added JMS Features

Understanding the JMS API

ConnectionFactory

Using the Default Connection Factories

Configuring and Deploying Connection Factories

The ConnectionFactory Class

Connection

Session

WebLogic JMS Session Guidelines

Session Subclasses

Non-Transacted Session

Transacted Session

Destination

Distributed Destinations

MessageProducer and MessageConsumer

Message

Message Header Fields

Message Property Fields

Message Body

ServerSessionPoolFactory

ServerSessionPool

ServerSession

ConnectionConsumer

Best Practices for Application Design

Message Design

Serializing Application Objects

Serializing strings

Server-side serialization

Selection

Message Compression

Message Properties and Message Header Fields

Message Ordering

Topics vs. Queues

Asynchronous vs. Synchronous Consumers

Persistent vs. Non-Persistent Messages

Deferring Acknowledges and Commits

Using AUTO_ACK for Non-Durable Subscribers

Alternative Qualities of Service, Multicast and No-Acknowledge

Using MULTICAST_NO_ACKNOWLEDGE

Using NO_ACKNOWLEDGE

Avoid Multi-threading

Developing a Basic JMS Application

Importing Required Packages

Setting Up a JMS Application

Step 1: Look Up a Connection Factory in JNDI

Step 5: Create Message Producers and Message Consumers Using the Session and Destinations

Create QueueSenders and QueueReceivers

Create TopicPublishers and TopicSubscribers

Step 6a: Create the Message Object (Message Producers)

Step 6b: Optionally Register an Asynchronous Message Listener (Message Consumers)

Step 7: Start the Connection

Example: Setting Up a PTP Application

Example: Setting Up a Pub/Sub Application

Sending Messages

Create a Message Object

Define a Message

Send the Message to a Destination

Send a Message Using Queue Sender

Send a Message Using TopicPublisher

Setting Message Producer Attributes

Example: Sending Messages Within a PTP Application

Example: Sending Messages Within a Pub/Sub Application

Receiving Messages

Receiving Messages Asynchronously

Asynchronous Message Pipeline

Configuring a Message Pipeline

Behavior of Pipelined Messages

Receiving Messages Synchronously

Using the Prefetch Mode to Create a Synchronous Message Pipeline

Example: Receiving Messages Synchronously Within a PTP Application

Example: Receiving Messages Synchronously Within a Pub/Sub Application

Recovering Received Messages

Acknowledging Received Messages

Releasing Object Resources

Managing Your Applications

Managing Rolled Back, Recovered, Redelivered, or Expired Messages

Setting a Redelivery Delay for Messages

Setting a Redelivery Delay

Overriding the Redelivery Delay on a Destination

Setting a Redelivery Limit for Messages

Configuring a Message Redelivery Limit On a Destination

Configuring an Error Destination for Undelivered Messages

Ordered Redelivery of Messages

Required Message Pipeline Setting for the Messaging Bridge and MDBs

Performance Limitations

Handling Expired Messages

Setting Message Delivery Times

Setting a Delivery Time on Producers

Setting a Delivery Time on Messages

Overriding a Delivery Time

Interaction With the Time-to-Live Value

Setting a Relative Time-to-Deliver Override

Setting a Scheduled Time-to-Deliver Override

JMS Schedule Interface

Managing Connections

Defining a Connection Exception Listener

Accessing Connection Metadata

Starting, Stopping, and Closing a Connection

Managing Sessions

Defining a Session Exception Listener

Closing a Session

Managing Destinations

Dynamically Creating Destinations

Dynamically Deleting Destinations

Preconditions for Deleting Destinations

What Happens when a Destination is Deleted

Message Timestamps for Troubleshooting Deleted Destinations

Deleted Destination Statistics

Using Temporary Destinations

Creating a Temporary Queue

Creating a Temporary Topic

Deleting a Temporary Destination

Setting Up Durable Subscriptions

Defining the Persistent Store

Defining the Client ID

Creating Subscribers for a Durable Subscription

Best Practice: Always Close Failed JMS ClientIDs

Deleting Durable Subscriptions

Modifying Durable Subscriptions

Managing Durable Subscriptions

Setting and Browsing Message Header and Property Fields

Setting Message Header Fields

Setting Message Property Fields

Browsing Header and Property Fields

Filtering Messages

Defining Message Selectors Using SQL Statements

Defining XML Message Selectors Using XML Selector Method

Displaying Message Selectors

Indexing Topic Subscriber Message Selectors To Optimize Performance

Sending XML Messages

WebLogic XML APIs

Using a String Representation

Using a DOM Representation

Using JMS Module Helper to Manage Applications

Configuring JMS System Resources Using JMSModuleHelper

Configuring JMS Servers and Store-and-Forward Agents

JMSModuleHelper Sample Code

Creating a JMS System Resource

Deleting a JMS System Resource

Best Practices when Using JMSModuleHelper

Using Multicasting with WebLogic JMS

Benefits of Using Multicasting

Limitations of Using Multicasting

Using WebLogic Server Unicast

Configuring Multicasting for WebLogic Server

Prerequisites for Multicasting

Step 1: Set Up the JMS Application, Creating Multicast Session and Topic Subscriber

Step 2: Set Up the Message Listener

Dynamically Configuring Multicasting Configuration Attributes

Example: Multicast TTL

Using Distributed Destinations

What is a Distributed Destination?

Why Use a Distributed Destination

Creating a Distributed Destination

Types of Distributed Destinations

Uniform Distributed Destinations

Weighted Distributed Destinations

Using Distributed Destinations

Using Distributed Queues

Using Distributed Topics

TopicPublishers

TopicSubscribers

Deploying Message-Driven Beans on a Distributed Topic

Accessing Distributed Destination Members

Accessing Uniform Destination Members

Accessing Weighted Destination Members

Distributed Destination Failover

Using Message-Driven Beans with Distributed Destinations

Common Use Cases for Distributed Destinations

Maximizing Production

Maximizing Availability

Using Queues

Using Topics

Stuck Messages

Enhanced Support for Using WebLogic JMS With EJBs and Servlets

Enabling WebLogic JMS Wrappers

Declaring JMS Objects as Resources In the EJB or Servlet Deployment Descriptors

Declaring a Wrapped JMS Connection Factory

Declaring JMS Destinations

Sending a JMS Message In a Java EE Container

What’s Happening Under the JMS Wrapper Covers

Automatically Enlisting Transactions

Container-Managed Security

Connection Testing

Java EE Compliance

Pooled JMS Connection Objects

Monitoring Pooled Connections

Improving Performance Through Pooling

Speeding Up JNDI Lookups by Pooling Session Objects

Speeding Up Object Creation Through Caching

Enlisting the Proper Transaction Mode

Examples of JMS Wrapper Functions

ejb-jar.xml

weblogic-ejb-jar.xml

PoolTest.java

PoolTestHome.java

PoolTestBean.java

Simplified Access to Remote or Foreign JMS Providers

Using Message Unit-of-Order

What Is Message Unit-Of-Order?

Understanding Message Processing with Unit-of-Order

Message Processing According to the JMS Specification

Message Processing with Unit-of-Order

Message Delivery with Unit-of-Order

Message Unit-of-Order Case Study

Joe Orders a Book

What Happened to Joe’s Order

How Message Unit-of-Order Solves the Problem

How to Create a Unit-of-Order

Creating a Unit-of-Order Programmatically

Creating a Unit-of-Order Administratively

Configuring Unit-of-Order for a Connection Factory and Destinations

Unit-of-Order Naming Rules

Message Unit-of-Order Advanced Topics

What Happens When a Message Is Delayed During Processing?

What Happens When a Filter Makes a Message Undeliverable

What Happens When Destination Sort Keys are Used

Using Unit-of-Order with Distributed Destinations

Using the Path Service

Using Hash-based Routing

Configuring Routing on Uniform Distributed Destinations

Using Unit-of-Order with Topics

Using Unit-of-Order with JMS Message Management

Using Unit-of-Order with WebLogic Store-and-Forward

Using Unit-of-Order with WebLogic Messaging Bridge

Limitations of Message Unit-of-Order

Using Unit-of-Work Message Groups

What Are Unit-of-Work Message Groups?

Understanding Message Processing With Unit-of-Work

Basic UOW Terminology

Rules For Processing UOW Messages

Message Unit-of-Work Case Study

Jill Orders Miscellaneous Items From an Online Retailer

How Message Unit-of-Work Completes the Order

How to Create a Unit-of-Work Message Group

How To Write a Producer to Set UOW Message Properties

Example UOW Producer Code

UOW Exceptions

How to Write a UOW Consumer and/or Producer For an Intermediate Destination

Configuring Terminal Destinations

UOW Message Routing for Terminal Distributed Destinations

How to Write a UOW Consumer For a Terminal Destination

Message Unit-of-Work Advanced Topics

Message Property Handling

System-Generated Properties

Final Component Message Properties

Component Message Heterogeneity

ReplyTo Message Property

UOW and Uniform Distributed Destinations

UOW and Store-and-Forward Destinations

Limitations of UOW Message Groups

Using Transactions with WebLogic JMS

Overview of Transactions

Using JMS Transacted Sessions

Step 1: Set Up JMS Application, Creating Transacted Session

Step 2: Perform Desired Operations

Step 3: Commit or Roll Back the JMS Transacted Session

Using JTA User Transactions

Step 1: Set Up JMS Application, Creating Non-Transacted Session

Step 2: Look Up User Transaction in JNDI

Step 3: Start the JTA User Transaction

Step 4: Perform Desired Operations

Step 5: Commit or Roll Back the JTA User Transaction

Asynchronous Messaging Within JTA User Transactions Using Message Driven Beans

Example: JMS and EJB in a JTA User Transaction

Using Cross Domain Security

WebLogic JMS C API

What Is the WebLogic JMS C API?

System Requirements

WebLogic JMS C API Code Examples

Design Principles

Java Objects Map to Handles

Thread Utilization

Exception Handling

Type Conversions

Memory Allocation and Garbage Collection

Closing Connections

Helper Functions

Security Considerations

Implementation Guidelines

Recovering from a Server Failure

Automatic JMS Client Failover

Automatic Failover for JMS Producers

Sample Producer Code

Re-usable ConnectionFactory Objects

Re-usable Destination Objects

Reconnected Connection Objects

Special Cases for Reconnected Connections

Reconnected Session Objects

Special Cases for Reconnected Sessions

Reconnected MessageProducer Objects

Special Case for Reconnected MessageProducers and Distributed Destinations

Configuring Automatic Failover for JMS Consumers

Sample Consumer Client Code

Configuring Automatic Client Refresh Options

Common Cases for Reconnected Consumers

Synchronous Consumers

Asynchronous Consumers

Special Cases for Reconnected Consumers

Consumers of Distributed Destinations

Message-Driven EJBs

Consumer Connections with a ClientID for Durable Subscriptions

Non-Durable Subscriptions and Possible Missed Messages

Duplicate Messages

Variations Due to Acknowledge Modes

Consumers May Not Reconnect with Migrated JMS Destinations In a Cluster

Explicitly Disabling Automatic Failover on JMS Clients

Programmatically

Administratively

Limitations for Automatic JMS Client Failover

Best Practices for JMS Clients Using Automatic Failover

Use Transactions to Group Message Work

JMS Clients Should Always Call the close() Method

Programming Considerations for WebLogic Server 9.0 or Earlier Failures

Migrating JMS Data to a New Server

Deprecated WebLogic JMS Features

Defining Server Session Pools

Step 1: Look Up Server Session Pool Factory in JNDI

Step 2: Create a Server Session Pool Using the Server Session Pool Factory

Create a Server Session Pool for Queue Connection Consumers

Create a Server Session Pool for Topic Connection Consumers

Step 3: Create a Connection Consumer

Create a Connection Consumer for Queues

Create a Connection Consumer for Topics

Example: Setting Up a PTP Client Server Session Pool

Example: Setting Up a Pub/Sub Client Server Session Pool

FAQs: Integrating Remote JMS Providers