Contents

Title and Copyright Information

Preface

• Documentation Accessibility
• Conventions

1 Introduction and Roadmap

• Document Scope and Audience
• Guide to this Document
• Related Documentation
• Samples and Tutorials for the JMS Developer
  • Avitek Medical Records Application (MedRec) and Tutorials
• New and Changed JMS Features In This Release

2 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

3 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
• Using the JMSXUserID Property
• Performance and Tuning

4 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 Factory using Deployment Descriptors
    • Declaring JMS Destinations using Deployment Descriptors
  • Referencing a Packaged JMS Application Module In Deployment Descriptor Files
    • Referencing Application Modules In a weblogic-application.xml Descriptor
    • Referencing JMS Resources In a WebLogic Application
    • Referencing JMS Resources In a Java EE Application
  • Declaring JMS Destinations and Connection Factories using Annotations
    • Injecting Resource Dependency into a Class
    • Non-Injected EJB 3.0 Resource Reference Annotations
  • Avoid Transactional XA Interfaces
• Disabling Wrapping and Pooling
• 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
• Simplified Access to Foreign JMS Providers
• Examples of JMS Wrapper Functions
  • Example of JMS Wrapper Functions
    • ejb-jar.xml
    • weblogic-ejb-jar.xml
    • PoolTest.java
    • PoolTestHome.java
    • PoolTestBean.java
  • Sending a JMS Message In a Java EE Container
    • Using comp/env
  • Dependency Injection
  • EJB 3.0 Wrapper Without Injection

5 Developing a Basic JMS Application

• Importing Required Packages
• Setting Up a JMS Application
  • Step 1: Look Up a Connection Factory in JNDI
  • Step 2: Create a Connection Using the Connection Factory
    • Create a Queue Connection
    • Create a Topic Connection
  • Step 3: Create a Session Using the Connection
    • Create a Queue Session
    • Create a Topic Session
  • Step 4: Look Up a Destination (Queue or Topic)
    • Using a JNDI Name
    • Use a Reference
  • Step 5: Create Message Producers and Message Consumers
    • Create QueueSenders and QueueReceivers
    • Create TopicPublishers and TopicSubscribers
  • Step 6a: Create the Message Object (Message Producers)
  • Step 6b: Optionally Register an Asynchronous Message Listener
  • Step 7: Start the Connection
  • Example: Setting Up a PTP Application
    • Step 1
    • Step 2
    • Step 3
    • Step 4
    • Step 5
    • Step 6
    • Step 7
  • Example: Setting Up a Pub/Sub Application
    • Step 1
    • Step 2
    • Step 3
    • Step 4
    • Step 5
    • Step 6
    • Step 7
• 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
  • Receiving Messages Synchronously
    • Use Prefetch Mode to Create a Synchronous Message Pipeline
    • Receiving Messages Synchronously Within a PTP Application
    • Receiving Messages Synchronously Within a Pub/Sub Application
  • Recovering Received Messages
• Acknowledging Received Messages
• Releasing Object Resources

6 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
  • Setting the Client ID Policy
  • Defining the Client ID
  • Creating a Sharable Subscription Policy
  • 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

7 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

8 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, Multicast Session and Topic Subscriber
  • Step 2: Set Up the Message Listener
  • Dynamically Configuring Multicasting Configuration Attributes
  • Example: Multicast TTL

9 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
    • Queue Forwarding
    • QueueSenders
    • QueueReceivers
    • QueueBrowsers
  • Using Replicated Distributed Topics
    • TopicPublishers
    • TopicSubscribers
    • Deploying Message-Driven Beans on a Distributed Topic
  • Using Partitioned Distributed Topics
  • Accessing Distributed 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

10 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
    • Unit-of-Order and Distributed Topics
    • Unit-of-Order, Topics, and Message Driven Beans
  • 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

11 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/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

12 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
• JTA User Transactions Using Message Driven Beans
• Example: JMS and EJB in a JTA User Transaction
  • Step 1
  • Step 2
  • Step 3
  • Step 4
  • Step 5
• Using Cross Domain Security

13 Developing Advanced Pub/Sub Applications

• Overview of Advanced High Availability Concepts
  • WebLogic Messaging High Availability Features
  • Application Design Limitations When using Replicated Distributed Topics
  • Advanced Topic Features
• Advanced Messaging Features for High Availability
  • Shared Subscriptions and Client ID Policy
    • What is the Subscription Key
    • Configuring a Shared Subscription
  • How Sharing a Non-Durable Subscription Works
    • How a Shared Subscription Policy for a Non-durable Subscription is Determined
    • How a Non-durable Subscription is Closed
  • How Sharing a Durable Subscription Works
    • How a Shared Subscription Policy for a Durable Subscription is Determined
    • How to Unsubscribe a Durable Subscription
    • Considerations when Unsubscribing a Durable Subscriber
    • Managing Durable Subscriptions
• Design Strategies when using Topics
  • One-copy-per-instance Design Strategy
  • One-copy-per-application Design Strategy
• Best Practices for Distributed Topics

14 Recovering from a Server Failure

• Automatic JMS Client Failover
  • Automatic Reconnect Limitations
  • Automatic Failover for JMS Producers
    • Sample Producer Code
    • Re-usable ConnectionFactory Objects
    • Re-usable Destination Objects
    • Reconnected Connection Objects
    • Reconnected Session Objects
    • Reconnected MessageProducer Objects
  • Configuring Automatic Failover for JMS Consumers
    • Sample Consumer Client Code
    • Configuring Automatic Client Refresh Options
    • Common Cases for Reconnected Consumers
    • Special Cases for Reconnected Consumers
  • Explicitly Disabling Automatic Failover on JMS Clients
    • Programmatically
    • Administratively
  • Best Practices for JMS Clients Using Automatic Failover
    • Always Catch exceptions
    • Use Transactions to Group Message Work
    • JMS Clients Should Always Call the close() Method
• Programming Considerations for WebLogic Server 9.0 or Earlier Failures
• Manually Migrating JMS Data to a New Server

15 WebLogic JMS C API

• What Is the WebLogic JMS C API?
• System Requirements
• Design Principles
  • Java Objects Map to Handles
  • Thread Utilization
  • Exception Handling
  • Type Conversions
    • Integer (int)
    • Long (long)
    • Character (char)
    • String
  • Memory Allocation and Garbage Collection
  • Closing Connections
  • Helper Functions
• Security Considerations
• Implementation Guidelines
• Workarounds for Client Crash Thread Detach Issue

A 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
    • Step 1
    • Step 2
    • Step 3
  • Example: Setting Up a Pub/Sub Client Server Session Pool
    • Step 1
    • Step 2
    • Step 3

B FAQs: Integrating Remote JMS Providers

• Understanding JMS and JNDI Terminology
• Understanding Transactions
• How to Integrate with a Remote Provider
• Best Practices when Integrating with Remote Providers
• Using Foreign JMS Server Definitions
• Using EJB/Servlet JMS Resource References
• Using WebLogic Store-and-Forward
• Using WebLogic JMS SAF Client
• Using a Messaging Bridge
• Using Messaging Beans
• Using AQ JMS
• JMS Interoperability Resources

C How to Lookup a Destination

• Use a JNDI Name
• Use a Create Destination Identifier
  • Default WebLogic CDI Syntax
  • Custom WebLogic CDI Syntax
  • Server Affinity When Looking Up Destinations
• Examples of Syntax Used to Lookup Destinations
  • Non-Distributed Destinations
    • JNDI Syntax for Non-distributed Destinations
    • CDI Syntax for Non-Distributed destinations
  • Uniform Distributed Destinations
    • JNDI Syntax for UDDs
    • CDI Syntax for UDDs
  • Weighted Distributed Destinations
    • JNDI Syntax for WDDs
    • CDI Syntax for WDDs

D Advanced Programming with Distributed Destinations Using the JMS Destination Availability Helper API

• Introduction
• Controlling DD Producer Load Balancing
  • Basic JMS
  • Senders to Distributed Queues (DQs) and Partitioned Distributed Topics (PDTs)
  • Senders to Replicated Distributed Topics (RDTs)
• Using the JMS Destination Availability Helper API
  • Overview
  • General Flow
  • Handling weblogic.jms.extension.DestinationDetail
  • Best Practices for Consumer Containers
    • When to Register and Unregister
    • URL Handling
    • Failure Handling
    • JNDI Context Handling
    • JMS Connection Handling
  • Interoperability Guide-Lines
    • API Availability
    • Foreign Contexts
    • Destination Type Support
    • Unavailable Notifications
    • Interoperating with Pre WebLogic Server 9.0 Distributed Queues
    • Interoperating with Pre WebLogic Server 10.3.4.0 Distributed Topics
    • DestinationDetail Fields
  • Security Considerations
    • WebLogic Server Security Model
    • Passing Credentials Between Threads
    • When to use Cross Domain Security
    • Authentication of Users
    • Securing Destinations
    • Securing Wire Data
  • Transaction Considerations
• Strategies for Uniform Distributed Queue Consumers
  • General Strategies
  • Best Practice for Local Server Consumers
• Strategies for Subscribers on Uniform Distributed Topics
  • One Copy per Instance
    • General Pattern Design Strategy for One Copy per Instance
    • Best Practice for Local Server Consumers using One Copy per Instance
  • One Copy per Application
    • General Pattern Design Strategy for One Copy per Application
    • Best Practice for Local Server Consumers using One Copy per Application