Building an Integration Process | BOOMI

Once a company logs into their account on the Boomi AtomSphere web site, integration processes can be designed and built using a visual designer that includes access to a library of pre-built connectors and process maps. Using familiar point-and-click, drag-and-drop techniques, users can build very simple to very sophisticated integration processes with exceptional speed. No coding is required.


Since its inception, Boomi has focused on simplifying the creation of integration processes for application integration, data integration, and B2B integration. By identifying the common steps needed to automate complex integration scenarios, a series of common integration components have been created and are available to all Boomi users. When developing an integration process, these components are connected to create an end-to-end integration workflow.







Standard Boomi Integration Components include:
Connector
connect to any application or data source
Always the first and last steps of an integration workflow, the Connector enables access to another application or data source. The connector sends/receives data and converts it into a normalized XML format. A Connector’s primary role is to "operationalize an API" by abstracting the technical details of an API and providing a wizard-based approach to configuring access to the associated application. Connectors are also configurable to capture only new or changed data, based on the last successful run date of an integration process.
Data Transformation
transform data from one format to another
While core to any integration, the data stored in various applications is rarely, if ever, semantically consistent. For example, a Customer represented in one application will have different fields and formats from that of another application. Using Boomi's Data Transformation components, users can map data from one format to another.

Any structured data format is supported, included XML, EDI, flat file, and database formats. While transforming data, the user can also invoke a variety of field-level transformations as well to transform, augment, or compute data fields. Over 50 standard functions are provided. Users can also create their own functions and re-use them in subsequent projects.
Decision
execute business logic and data integrity checks
Boomi’s Decision components enable true/false data validation that enables users to explicitly handle a result based on the programmed logic. For example, an order can be checked against the target system to see if it has already been processed. Based upon the outcome of the data check, the request will be routed down either the 'true' or 'false' path. Other examples include checking products referenced in an invoice to ensure they exist before processing the invoice, etc.
Cleanse
data cleansing and validation
Integrations are only as successful as the quality of data that gets exchanged. Boomi’s Cleanse components allow users to validate and "clean" data on a field-by-field, row-by-row basis to ensure that fields are the right data type, the right length, and the right numeric format (e.g. currency). Users have an option of specifying whether they wish to attempt to auto-repair bad data or simply reject rows that are “dirty”. All validation results are routed through a “clean” or “rejected” path which allows users to explicitly handle either scenario.
Message
user-defined dynamic notifications
For any step of the integration workflow, Message components can be used to create dynamic notifications that make use of content from the actual data being integrated. This allows the creation of messages like "Invoice 1234 was successfully processed for customer ABC Inc." Connectors are then used to deliver the message to the appropriate end point.
Route
dynamic, content based routing
Route components examine any of the content in the actual data being processed or use numerous other properties available to the user (such as directory, file name, etc.) and route the extracted data down specific paths of execution.
Split
intelligent data splitting and aggregation
Split components re-organize data into logical representations, such as business transactions. For example, you can take incoming invoice headers and details, and create logical invoice documents to ensure the applications being integrated process or reject the entire invoice vs. discrete pieces.
Testing Integrations
Real-time
To further simplify and shorten the integration development cycle, users can test their integrations directly in the Build environment. Integration testing includes watching as the data moves through the integration process, viewing the actual data, monitoring exactly where the integration fails, and click-thru on the failed step to examine error messages.





Configuring Integration Automation
Integration processes can be configured for “hands off” execution. AtomSphere provides both real-time as well as batch-style automation options depending on the requirements of the integration, as defined below:

Event-based Invocation - direct Atom invocation.

Included in every Boomi Atom is a lightweight HTTP Server. Data can be HTTP-posted to a specific Atom, and that data will be processed in real-time.
Event-based Invocation - remote Atom invocation.

Boomi also provides a Trigger API, which allows you to securely invoke an integration process that is running inside an Atom, regardless of where that Atom may be running, without opening any holes in the firewall. This is a very powerful option when you wish to provide external access to integration processes or trigger an integration based on some event in another application.
Schedule-based Invocation

Included in every Boomi Atom is a schedule manager, capable of invoking integration processes based on a schedule configured by the user. Invocations can be scheduled to run as frequently as every minute. Schedule-based invocation option requires no changes to external applications.
.

BOOMI

Boomi AtomSphere Frequently Asked Questions
Q: How do I access AtomSphere?
A: Because AtomSphere is an online service, there is no appliance or software to buy, install or maintain. Just point your browser to the login page at www.boomi.com and login.

Q: How do I sign up for AtomSphere? Can I download a demo?
A: You can sign up for a free trial under the ’30 Day Free Trial’ section of the Boomi website.

Q: What applications can I integrate using AtomSphere?
A: An up-to-date list of supported applications can be found on our website.

Q: Is any training required to learn to use AtomSphere?
A: AtomSphere is designed to be user friendly and anyone with basic IT skills and knowledge of the applications they plan to integrate should be able to build integration processes easily. Our customers have reported that using AtomSphere is similar to using other web-based software. However, Boomi’s Support Team offers weekly training sessions via webinar.

Q: Is there any training involved/included?
A: We hold various training/webinar series throughout each month, including a Boomi Basics Course every Monday at 12:30pm EST. You can find full details on all upcoming webinars at www.boomi.com/news_and_events

Q: What Support is available?
A: We have many support options to give you the help you need:

Free 30 Day Trial! Go to www.boomi.com
Submit support tickets to support@boomi.com
Live Chat – 8am-9pm ET is embedded into the application
Forums
Help Wiki Documentation
Premier Support
Boomi Basics Training Webinar Series - Every Monday @ 12:30pm EST
Q: How do I contact Customer Support?
A: All of the available options for support are listed in the above question. Your easiest and quickest path to access support is through the Live Chat embedded into Boomi AtomSphere.

Q: What sort of skill set is required to configure AtomSphere?
A: We aim for our service to be a visual, configuration based approach to integration. You do not need to be a developer to utilize the service; you simply need to understand where the data resides in the source system and where the data needs to be integrated in the destination system. The typical roles that utilize AtomSphere would include Systems Analyst, Application Administrator, or Business Process Engineer.

Q: What platforms do I need to have in order to run AtomSphere?
A: Since Boomi hosts the application, all you need is a computer or an alternative device that can run a Web browser. It doesn’t matter what type of hardware or operating system you’re running.

Q: What involvement is required from my company’s IT department to set up my integration processes?
A: Very minimal involvement from your IT department is typically needed. Typical involvement from the IT department would include allowing you access to the source/destination applications or allowing you to install a Boomi Atom to gain access to your on premise application.

Q: Can Boomi’s customer support team help me set up my integrations?
A: We have designed AtomSphere to be largely self-service and our website contains a number of resources to help you including documentation, videos, webinars, and training courses that are free. You also have access to Boomi forums and “chat” support from within AtomSphere . Your support level will determine the availability of these services and specific response times. Consulting services are also always available from our professional services team for a fee.

Boomi Basics
Q: What’s an Atom?
A: An Atom™ is a lightweight, dynamic runtime engine created with patent pending-technology, Boomi Atoms contain all the components required to execute an integration process. There is a full-featured dashboard to monitor the status and health of all Atoms and integration processes whether they are deployed in the cloud or on-premise.

Q: Where are Atoms hosted?
A: Boomi Atoms are completely self-contained and autonomous and can be run on virtually any server. They can be deployed “in the cloud” for SaaS to SaaS integration (e.g. Boomi’s data center, an ISVs data center or a third-party data center such as Amazon) or behind a company’s firewall for SaaS to On Premise integration.

Q: What is an Integration Process?
A: The main component in a Boomi integration is the Process. A Process represents a business process- or transaction-level interface between two or more systems. Examples of a Process might be “Salesforce Account Synchronization to accounting system” or “Sales Orders from Company ABC to QuickBooks.” Processes contain a left-to-right series of Shapes connected together like a flow chart to illustrate the steps required to transform, route, and otherwise manipulate the data from source to destination.

Q: What is a Connector?
A: Connectors get and send data in and out of Processes. They enable communication with the applications or data sources between which data needs to move or, in other words, the “end points” of the Process. Those applications and data sources can range from traditional on-premise applications like SAP and QuickBooks to Web-based applications like Salesforce.com and NetSuite to data repositories like an FTP directory, a commercial database, or even an email server.

Q: How does Boomi differ from an Application Programming Interface (API)?
A: An API opens up secure access to data in an application but it does not accomplish the integration itself. An API is like an electrical socket – until something is plugged into it, it just sits there. Boom integration Connectors are like “plugs.” Boomi Connectors plug into and API and abstract the technical details of the API and transportation protocols used to communicate with various applications and data sources, allowing you to focus on the business data and logic of the integration. A Connector is really a combination of two Components: a Connection and an Operation. Think of the Connection as the where and the Operation as the how. These two components determine the type of data source, how to physically connect to it, and what type of data records to exchange.

Q: Are there any limitations to the kind/amount of information being integrated?
A: No, we have benchmarked the Boomi Atom to be able to handle very large volumes, upwards of 1,000,000 records an hour.

Q: How often would we need to run the integration? How close to real time information can I get?
A: We support both real-time event-based and schedule-driven executions. We have a scheduler built into Boomi AtomSphere. You can schedule an integration to run based on intervals you define (up to every 1 minute) or on an advanced schedule (more flexible). We also have an external API that will allow you to call an integration to be run in real-time from an external source or application.

Q: Are the integrations manageable by either event OR specific dates?
A: Yes, our system will allow you to schedule your integration process to run at specific dates/intervals, up to every one minute. We also provide an API that will allow you to include event driven integration into your integration process.

Q: Does AtomSphere integrate with shopping carts & e-commerce functionality?
A: Yes, please refer to our website for a full list of supported applications.

Q: If Boomi’s platform is hosted in “the cloud”, how can I integrate my on-premise data and legacy applications?
A: We offer the ability to deploy a Boomi Atom behind your firewall. This Boomi Atom is the run time engine that gives you secure access to your on premise application without having to make any changes to your firewall.

Using Boomi
Q: How do you ensure the data is secure during the integration process?
A: Boomi AtomSphere Connectors go through application specific security reviews where applicable. All data that is passed between the Boomi Atom onsite and our data center is sent over a secure HTTPs channel with 128 bit encryption. Learn more about AtomSphere’s security

Q: How is error handling managed?
A: Error handling is administered via our ‘manage’ tab where users can see the integration process, its executions and all associated log and status notifications. Boomi AtomSphere also includes retry capabilities to ensure messages that had an error during transit are delivered; an Atom also tracks its state to ensure that only unique data is processed. Finally, decision logic can be configured to query destination applications to ensure duplicate data is not sent to the application.

Q: If I have on-premise sources, how do I test my integration process in the hosted environment? Do I have to deploy an atom to do my testing?
A: Yes, the Boomi Atom would reside onsite, allowing you access to the on-premise application through Boomi AtomSphere.

Q: Does the internet and/or AtomSphere need to be up for my Atom to run?
A: Yes, because the Boomi Atom that resides onsite has no GUI, it must be in fairly constant contact with the data center. One important design aspect of AtomSphere is that, much like the Internet itself, it is a distributed architecture, eliminating single points of failure. It is important to note that even during planned maintenance of the platform, deployed Atoms continue to run and process normally.

Q: Do you have rollbacks for changes to an integration process?
A: Yes, we offer version control for our integration process allowing you to rollback to a previous integration process should the need arise.

Q: Is Test Mode an actual test of the process flow of the integration and is the destination getting updated/changed?
A: Yes, test mode actually executes the integration process as designed, so the source and destination will get updated. Boomi AtomSphere provides the concept of ‘Environments’ for those that wish to have the same integration process pointed to different locations (ie. Test, QA, Production).

OID

Oracle Internet Directory runs as an application on an Oracle Database. It communicates with the database by using Oracle Net Services, Oracle's operating system-independent database connectivity solution. The database may or may not be on the same host

Setting the JVM Heap Size for OC4J Processes

If you have sufficient memory available on your system and your application is memory intensive, you can improve your application performance by increasing the JVM heap size from the default value. While the amount of heap size required varies based on the application and on the amount of memory available, for most OC4J server applications, a heap size of at least 256 Megabytes is advised. If you have sufficient memory, using a heap size of 512 Megabytes or larger is preferable.

To change the size of the heap allocated to the OC4J processes in an OC4J instance, use the procedures outlined in "Using Application Server Control Console to Change JVM Command Line Options", and specify the following Java options:

-Xmssizem -Xmxsizem

Where size is the desired Java heap size in megabytes.

If you know that your application will consistently require a larger amount of heap, you can improve performance by setting the minimum heap size equal to the maximum heap size, by setting the JVM -Xms size to be the same as the -Xmx size.

For example, to specify a heap size of 512 megabytes, specify the following:

-Xms512m -Xmx512m

You should set your maximum Java heap size so that the total memory consumed by all of the JVMs running on the system does not exceed the memory capacity of your system. If you select a value for the Java heap size that is too large for your hardware configuration, one or more of the OC4J processes within the OC4J instance may not start, and Oracle Enterprise Manager 10g Application Server Control Console reports an error. Review the log files for the OC4J instance in the directory $ORACLE_HOME/opmn/logs, to find the error report:

Could not reserve enough space for object heap
Error occurred during initialization of VM

If you select a value for the JVM heap size that is too small, none of the OC4J processes will be able to start, and, after a timeout while attempting to make the change, Application Server Control Console reports an error, "An error occurred while restarting..." In this case, if you review the log files for the OC4J instance in the directory $ORACLE_HOME/opmn/logs, you may find errors similar to the following:

java.lang.OutOfMemoryError

Oracle SOA Suite

Oracle SOA Suite is a comprehensive, hot-pluggable software suite to build, deploy and manage Service-Oriented Architectures (SOA). The components of the suite benefit from common capabilities including consistent tooling, a single deployment and management model, end-to-end security and unified metadata management.

Oracle SOA Suite's hot-pluggable architecture helps businesses lower upfront costs by allowing maximum re-use of existing IT investments and assets, regardless of the environment (OS, application server, etc.) they run in, or the technology they were built upon. Its easy-to-use, re-use focused, unified application development tooling and end-to-end lifecycle management support further reduces development and maintenance cost and complexity.

The products contained in this suite are listed in the Component Index below. You can use that list to navigate to the individual product pages.

Deploying a portlet to the WebLogic portal

Deploying a portlet to the WebLogic portal
WebLogic provides the ability to create and host multiple application server configurations, called domains, on a single host machine.

You can create and configure as many domains as you would like. In order to run multiple domains simultaneously, however, you must configure each on a different listening port.

Procedure

To deploy a portlet to a WebLogic portal:

1.Start the WebLogic Platform Configuration wizard.
2.Select Basic WebLogic Portal Domain from the tree view
3.Select Express if this is the only domain you need to have running, otherwise select Custom and configure the Listen port number.
4.Accept the remaining default settings.
5.Modify the startWebLogic.cmd(sh) file of the newly created domain to add the following (after the call setDomainEnv command), substituting your content integration server installation directory where you see IICE_HOME:
call "%DOMAIN_HOME%\setDomainEnv.cmd" %*

@REM SET VENICE BRIDGE OPTIONS
set JAVA_OPTIONS=-Dvbr.home=IICE_HOME
set PATH=%PATH%;IICE_HOME/datastore
set CLASSPATH=%CLASSPATH%;IICE_HOME/datastore/datastore.jar6.Start the portal domain.
7.Deploy the content integration server EAR file (IICE_HOME/VeniceBridge.ear).
8.Verify that the content integration server Web client is running by accessing http://portaldomain_host:portdomain_port/webclient

Understanding WebLogic JMS

Understanding WebLogic JMS
These sections briefly review the different Java Message Service (JMS) concepts and features, and describe how they work with other application objects and WebLogic Server.

It is assumed the reader is familiar with Java programming and JMS 1.1 concepts and features.

■Overview of the Java Message Service and WebLogic JMS
■Understanding the Messaging Models
■Value-Added Public JMS API Extensions
■Understanding the JMS API



--------------------------------------------------------------------------------

Overview of the Java Message Service and WebLogic JMS
WebLogic JMS is an enterprise-class messaging system that is tightly integrated into the WebLogic Server platform. It fully supports the JMS Specification and also provides numerous WebLogic JMS Extensions that go above and beyond the standard JMS APIs.

What Is the Java Message Service?
An enterprise messaging system enables applications to communicate with one another through the exchange of messages. A message is a request, report, and/or event that contains information needed to coordinate communication between different applications. A message provides a level of abstraction, allowing you to separate the details about the destination system from the application code.

The Java Message Service (JMS) is a standard API for accessing enterprise messaging systems. Specifically, JMS:

■Enables Java applications sharing a messaging system to exchange messages
■Simplifies application development by providing a standard interface for creating, sending, and receiving messages
The following figure illustrates WebLogic JMS messaging.

Figure 2-1 WebLogic JMS Messaging





As illustrated in the figure, WebLogic JMS accepts messages from producer applications and delivers them to consumer applications.

Implementation of Java Specifications
WebLogic Server is compliant with the following Java specifications.

Java EE Specification
WebLogic Server is compliant with the Java Platform, Enterprise Edition (Java EE) Version 5.0 specification.

JMS Specification
WebLogic Server is fully compliant with the JMS 1.1 Specification and can be used in production.

WebLogic JMS Architecture
The following figure illustrates the WebLogic JMS architecture.

Figure 2-2 WebLogic JMS Architecture



Major Components
The major components of the WebLogic JMS Server architecture, as illustrated in Figure 2-2, include:

■JMS servers that can host a defined set of modules and any associated persistent storage that reside on a WebLogic Server instance.
■JMS modules contains configuration resources (such as queues, topics, and connections factories) and are defined by XML documents that conform to the weblogic-jms.xsd schema.
■Client JMS applications that either produce messages to destinations or consume messages from destinations.
■JNDI (Java Naming and Directory Interface), which provides a resource lookup facility. JMS resources such as connection factories and destinations are configured with a JNDI name. The runtime implementations of these resources are then bound into JNDI using the given names.
■WebLogic persistent storage (file store or JDBC-accessible) for storing persistent message data.



--------------------------------------------------------------------------------

Understanding the Messaging Models
JMS supports two messaging models: point-to-point (PTP) and publish/subscribe (pub/sub). The messaging models are very similar, except for the following differences:

■PTP messaging model enables the delivery of a message to exactly one recipient.
■Pub/sub messaging model enables the delivery of a message to multiple recipients.
Each model is implemented with classes that extend common base classes. For example, the PTP class javax.jms.Queue and the pub/sub class javax.jms.Topic both extend the class javax.jms.Destination.

Each message model is described in detail in the following sections.

Note: The terms producer and consumer are used as generic descriptions of applications that send and receive messages, respectively, in either messaging model. For each specific messaging model, however, unique terms specific to that model are used when referring to producers and consumers.

Point-to-Point Messaging
The point-to-point (PTP) messaging model enables one application to send a message to another. PTP messaging applications send and receive messages using named queues. A queue sender (producer) sends a message to a specific queue. A queue receiver (consumer) receives messages from a specific queue.

The following figure illustrates PTP messaging.

Figure 2-3 Point-to-Point (PTP) Messaging




Multiple queue senders and queue receivers can be associated with a single queue, but an individual message can be delivered to only one queue receiver.

If multiple queue receivers are listening for messages on a queue, WebLogic JMS determines which one will receive the next message on a first come, first serve basis. If no queue receivers are listening on the queue, messages remain in the queue until a queue receiver attaches to the queue.

Publish/Subscribe Messaging
The publish/subscribe (pub/sub) messaging model enables an application to send a message to multiple applications. Pub/sub messaging applications send and receive messages by subscribing to a topic. A topic publisher (producer) sends messages to a specific topic. A topic subscriber (consumer) retrieves messages from a specific topic.

The following figure illustrates pub/sub messaging.

Figure 2-4 Publish/Subscribe (Pub/Sub) Messaging





Unlike with the PTP messaging model, the pub/sub messaging model allows multiple topic subscribers to receive the same message. JMS retains the message until all topic subscribers have received it.

The Pub/Sub messaging model supports durable subscribers, allowing you to assign a name to a topic subscriber and associate it with a user or application. For more information about durable subscribers, see Setting Up Durable Subscriptions.

Message Persistence
As per the “Message Delivery Mode” section of the JMS Specification, messages can be specified as persistent or non-persistent:

■A persistent message is guaranteed to be delivered once-and-only-once. The message cannot be lost due to a JMS provider failure and it must not be delivered twice. It is not considered sent until it has been safely written to a file or database. WebLogic JMS writes persistent messages to a WebLogic persistent store (disk-base file or JDBC-accessible database) that is optionally targeted by each JMS server during configuration.
■Non-persistent messages are not stored. They are guaranteed to be delivered at-most-once, unless there is a JMS provider failure, in which case messages may be lost, and must not be delivered twice. If a connection is closed or recovered, all non-persistent messages that have not yet been acknowledged will be redelivered. Once a non-persistent message is acknowledged, it will not be redelivered.
For information about using the system-wide, WebLogic Persistent Store, see Using the WebLogic Persistent Store.




--------------------------------------------------------------------------------

Value-Added Public JMS API Extensions
WebLogic JMS is tightly integrated into the WebLogic Server platform, allowing you to build highly-secure Java EE applications that can be easily monitored and administered through the WebLogic Server console. In addition to fully supporting XA transactions, WebLogic JMS also features high availability through its clustering and service migration features, while also providing seamless interoperability with other versions of WebLogic Server and third-party messaging providers.

For a detailed listing of these value-added features, see “WebLogic Server Value-Added JMS Features” in Configuring and Managing WebLogic JMS.

WebLogic Server Value-Added JMS Features
In addition to the standard JMS APIs specified by the JMS Specification, WebLogic Server provides numerous weblogic.jms.extensions APIs, which includes the classes and methods described in the following table.

Table 2-1 WebLogic JMS Public API Extensions Interface/Class Function
ConsumerInfo,
DestinationInfo Provides consumer and destination information to management clients in CompositeData format.
JMSMessageFactoryImpl,
WLMessageFactory Provides a factory and methods to:
■Create JMS messages
■Create JMS bytes messages
■Create JMS map messages
■Creating JMS object messages
■Creating JMS stream messages
■Creating JMS text messages
■Creating JMS XML messages

JMSMessageInfo Provide browsing and message manipulation using JMX.
JMSModuleHelper,
JMSNamedEntityModifier Monitors JMS runtime MBeans and manages JMS Module configuration entities in a JMS module.
JMSRuntimeHelper Monitors JMS runtime JMX MBeans.
MDBTransaction Associates a message delivered to a MDB (message-driven bean) with a transaction.
WLDestination Determines if a destination is a queue or a topic.
WLMessage Sets a delivery time for messages, redelivery limits, and send timeouts.
WLMessageProducer Sets a message delivery times for producers and Unit-of-Order names.
WLQueueSession,
WLSession,
WLTopicSession Provides additional fields and methods that are not supported by javax.jms.QueueSession, javax.jms.Session, and javax.jms.TopicSession.
XMLMessage Creates XML messages.
Schedule Sets a scheduled delivery times for messages.
JMSHelper Monitors JMS runtime MBeans.
Deprecated in this release of WebLogic Server. Replaced by JMSModuleHelper.
ServerSessionPoolFactory,
ServerSessionPoolListener Provides interfaces for creating server session pools and message listeners.

Note: Session pool configuration objects are deprecated for this release of WebLogic Server. They are not a required part of the Java EE specification, do not support JTA user transactions, and are largely superseded by message-driven beans (MDBs), which are a required part of Java EE. For more information on designing MDBs, see “Message-Drive EJBs” in Programming WebLogic Enterprise JavaBeans.




This API also supports NO_ACKNOWLEDGE and MULTICAST_NO_ACKNOWLEDGE acknowledge modes, and extended exceptions, including throwing an exception:

■To the session exception listener (if set), when one of its consumers has been closed by the server as a result of a server failure, or administrative intervention.
■From a multicast session when the number of messages received by the session, but not yet delivered to the message listener, exceeds the maximum number of messages allowed for that session.
■From a multicast consumer when it detects a sequence gap (message received out of sequence) in the data stream.



--------------------------------------------------------------------------------

Understanding the JMS API
To create a JMS applications, use the javax.jms API. The API allows you to create the class objects necessary to connect to the JMS, and send and receive messages. JMS class interfaces are created as subclasses to provide queue- and topic-specific versions of the common parent classes.

The following table lists the JMS classes described in more detail in subsequent sections. For a complete description of all JMS classes, see the javax.jms or weblogic.jms.extensions Javadoc.

Table 2-2 WebLogic JMS Classes JMS Class Description
ConnectionFactory Encapsulates connection configuration information. A connection factory is used to create connections. You look up a connection factory using JNDI.
Connection Represents an open communication channel to the messaging system. A connection is used to create sessions.
Session Defines a serial order for the messages produced and consumed.
Destination Identifies a queue or topic, encapsulating the address of a specific provider. Queue and topic destinations manage the messages delivered from the PTP and pub/sub messaging models, respectively.
MessageProducer and MessageConsumer Provides the interface for sending and receiving messages. Message producers send messages to a queue or topic. Message consumers receive messages from a queue or topic.
Message Encapsulates information to be sent or received.
ServerSessionPoolFactory1 Encapsulates configuration information for a server-managed pool of message consumers. The server session pool factory is used to create server session pools.
ServerSessionPool2 Provides a pool of server sessions that can be used to process messages concurrently for connection consumers.
ServerSession3 Associates a thread with a JMS session.
ConnectionConsumer4 Specifies a consumer that retrieves server sessions to process messages concurrently.
1Supports an optional JMS interface for processing multiple messages concurrently.

2Supports an optional JMS interface for processing multiple messages concurrently.

3Supports an optional JMS interface for processing multiple messages concurrently.

4Supports an optional JMS interface for processing multiple messages concurrently.



For information about configuring JMS resources, see “Configuring JMS System Resources” in Configuring and Managing WebLogic JMS. The procedure for setting up a JMS application is presented in Setting Up a JMS Application.

ConnectionFactory
A ConnectionFactory encapsulates connection configuration information, and enables JMS applications to create a Connection. A connection factory supports concurrent use, enabling multiple threads to access the object simultaneously. You can use the preconfigured default connection factories provided by WebLogic JMS, or you can configure one or more connection factories to create connections with predefined attributes that suit your application.

Using the Default Connection Factories
WebLogic JMS defines two default connection factories, which you can look up using the following JNDI names:

■weblogic.jms.ConnectionFactory
■weblogic.jms.XAConnectionFactory
You only need to create a user-defined a connection factory if the settings of the default factories are not suitable for your application. The main difference between the preconfigured settings for the default connection factories is the default value for the “XA Connection Factory Enabled” attribute which is used to enable JTA transactions, as shown in the following table.


Table 2-3 XA Transaction(al) Settings for Default Connection Factories Default Connection Factory. . . XA Connection Factory Enabled setting is. . .
weblogic.jms.ConnectionFactory False
weblogic.jms.XAConnectionFactory True


An XA factory is required for JMS applications to use JTA user-transactions, but is not required for transacted sessions. For more information about using transactions with WebLogic JMS, see Using Transactions with WebLogic JMS.

All other default factory configuration attributes are set to the same default values as a user-defined connection factory.

For more information about the XA Connection Factory Enabled attribute, and to see the default values for the other connection factory attributes, see “JMS Connection Factory: Configuration: Transactions” in the Administration Console Online Help.

Another distinction when using the default connection factories is that you have no control over targeting the WebLogic Server instances where the connection factory may be deployed. However, you can disable the default connection factories on a per-server basis.

For more information on enabling or disabling the default connection factories, see “Servers: Configuration: Services” in the Administration Console Online Help.

To deploy a connection factory on specific independent servers, on specific servers within a cluster, or on an entire cluster, you must configure a new connection factory and specify the appropriate target, as explained in Connection Factory Configuration in Configuring and Managing WebLogic JMS.

Note: For backwards compatibility, WebLogic JMS still supports two deprecated default connection factories. The JNDI names for these factories are: javax.jms.QueueConnectionFactory and javax.jms.TopicConnectionFactory.

Configuring and Deploying Connection Factories
A system administrator can define and configure one or more connection factories to create connections with predefined attributes and WebLogic Server will add them to the JNDI space during startup. The application then retrieves a connection factory using WebLogic JNDI. Any user-defined connection factories must be uniquely named.

For information on configuring connection factories, see “Configure connection factories” in the Administration Console Online Help.

A system administrator establishes cluster-wide, transparent access to JMS destinations from any server in the cluster by targeting to the cluster or by targeting to one or more server instances in the cluster. This way, each connection factory can be deployed on multiple WebLogic Server instances. For more information on JMS clustering, refer to “Configuring Clustered WebLogic JMS Resources” in Configuring and Managing WebLogic JMS.

The ConnectionFactory Class
The ConnectionFactory class does not define methods; however, its subclasses define methods for the respective messaging models. A connection factory supports concurrent use, enabling multiple threads to access the object simultaneously.

Note: For this release, you can use the JMS Version 1.1 specification connection factories or you can choose to use the subclasses.

The following table describes the ConnectionFactory subclasses.

Table 2-4 ConnectionFactory Subclasses Subclass. . . In Messaging Model. . . Is Used to Create. . .
QueueConnectionFactory PTP QueueConnection to a JMS PTP provider.
TopicConnectionFactory Pub/Sub TopicConnection to a JMS Pub/Sub provider.


To learn how to use the ConnectionFactory class within an application, see Developing a Basic JMS Application, or the javax.jms.ConnectionFactory Javadoc.

Connection
A Connection represents an open communication channel between an application and the messaging system, and is used to create a Session for producing and consuming messages. A connection creates server-side and client-side objects that manage the messaging activity between an application and JMS. A connection may also provide user authentication.

A Connection is created by a ConnectionFactory, obtained through a JNDI lookup.

Due to the resource overhead associated with authenticating users and setting up communications, most applications establish a single connection for all messaging. In the WebLogic Server, JMS traffic is multiplexed with other WebLogic services on the client connection to the server. No additional TCP/IP connections are created for JMS. Servlets and other server-side objects may also obtain JMS Connections.

By default, a connection is created in stopped mode. For information about how and when to start a stopped connection, see Starting, Stopping, and Closing a Connection.

Connections support concurrent use, enabling multiple threads to access the object simultaneously.

Note: For this release, you can use the JMS Version 1.1 specification connection objects or you can choose to use the subclasses.

The following table describes the Connection subclasses.

Table 2-5 Connection Subclasses Subclass. . . In Messaging Model. . . Is Used to Create. . .
QueueConnection PTP QueueSessions, and consists of a connection to a JMS PTP provider created by QueueConnectionFactory.
TopicConnection Pub/sub TopicSessions, and consists of a connection to a JMS pub/sub provider created by TopicConnectionFactory.


To learn how to use the Connection class within an application, see Developing a Basic JMS Application, or the javax.jms.Connection Javadoc.

Session
A Session object defines a serial order for the messages produced and consumed, and can create multiple message producers and message consumers. The same thread can be used for producing and consuming messages. If an application wants to have a separate thread for producing and consuming messages, the application should create a separate session for each function.

A Session is created by a Connection.

WebLogic JMS Session Guidelines
The JMS 1.1 Specification allows for a generic session to have a MessageConsumer for any type of Destination object. However, WebLogic JMS does not support having both types of MessageConsumer (QueueConsumer and TopicSubscriber) for a single session. In addition, having multiple consumers for a single session is not a common practice. The following commonly-used scenarios are supported, however:

■Using a single session with both a QueueSender and a TopicSubscriber (and vice-versa: QueueConsumer and TopicPublisher).
■Multiple MessageProducers of any type.
Caution: A session and its message producers and consumers can only be accessed by one thread at a time. Their behavior is undefined if multiple threads access them simultaneously.

Session Subclasses
The following table describes the Session subclasses.

Table 2-6 Session Subclasses Subclass. . . In Messaging Model. . . Provides a Context for. . .
QueueSession PTP Producing and consuming messages for a JMS PTP provider. Created by QueueConnection.
TopicSession Pub/sub Producing and consuming messages for a JMS pub/sub provider. Created by TopicConnection.


To learn how to use the Session class within an application, see Developing a Basic JMS Application, or the javax.jms.Session and weblogic.jms.extensions.WLSession javadocs.

Non-Transacted Session
In a non-transacted session, the application creating the session selects one of the five acknowledge modes defined in the following table.

Table 2-7 Acknowledge Modes Used for Non-Transacted Sessions Acknowledge Mode Description
AUTO_ACKNOWLEDGE The Session object acknowledges receipt of a message once the receiving application method has returned from processing it.
CLIENT_ACKNOWLEDGE The Session object relies on the application to call an acknowledge method on a received message. Once the method is called, the session acknowledges all messages received since the last acknowledge.
This mode allows an application to receive, process, and acknowledge a batch of messages with one call.

Note: In the Administration Console, if the Acknowledge Policy attribute on the connection factory is set to Previous, but you want to acknowledge all received messages for a given session, then use the last message to invoke the acknowledge method.


For more information on the Acknowledge Policy attribute, see “JMS Connection Factory: Configuration: General” in the Administration Console Online Help.
DUPS_OK_ACKNOWLEDGE The Session object acknowledges receipt of a message once the receiving application method has returned from processing it; duplicate acknowledges are permitted.
This mode is most efficient in terms of resource usage.

Note: You should avoid using this mode if your application cannot handle duplicate messages. Duplicate messages may be sent if an initial attempt to deliver a message fails.


NO_ACKNOWLEDGE No acknowledge is required. Messages sent to a NO_ACKNOWLEDGE session are immediately deleted from the server. Messages received in this mode are not recovered, and as a result messages may be lost and/or duplicate message may be delivered if an initial attempt to deliver a message fails.
This mode is supported for applications that do not require the quality of service provided by session acknowledge, and that do not want to incur the associated overhead.

Note: You should avoid using this mode if your application cannot handle lost or duplicate messages. Duplicate messages may be sent if an initial attempt to deliver a message fails.


MULTICAST_NO_ACKNOWLEDGE Multicast mode with no acknowledge required.
Messages sent to a MULTICAST_NO_ACKNOWLEDGE session share the same characteristics as NO_ACKNOWLEDGE mode, described previously.
This mode is supported for applications that want to support multicasting, and that do not require the quality of service provided by session acknowledge. For more information on multicasting, see Using Multicasting with WebLogic JMS.

Note: Use only with topics. You should avoid using this mode if your application cannot handle lost or duplicate messages. Duplicate messages may be sent if an initial attempt to deliver a message fails.




Transacted Session
In a transacted session, only one transaction is active at any given time. Any number of messages sent or received during a transaction are treated as an atomic unit.

When you create a transacted session, the acknowledge mode is ignored. When an application commits a transaction, all the messages that the application received during the transaction are acknowledged by the messaging system and messages it sent are accepted for delivery. If an application rolls back a transaction, the messages that the application received during the transaction are not acknowledged and messages it sent are discarded.

JMS can participate in distributed transactions with other Java services, such as EJB, that use the Java Transaction API (JTA). Transacted sessions do not support this capability as the transaction is restricted to accessing the messages associated with that session. For more information about using JMS with JTA, see Using JTA User Transactions.

Destination
A Destination object can be either a queue or topic, encapsulating the address syntax for a specific provider. The JMS specification does not define a standard address syntax due to the variations in syntax between providers.

Similar to a connection factory, an administrator defines and configures the destination and the WebLogic Server adds it to the JNDI space during startup. Applications can also create temporary destinations that exist only for the duration of the JMS connection in which they are created.

Note: Administrators can also configure a distributed destination, which is a single set of destinations (queues or topics) that are accessible as a single, logical destination to a client. For more information, see Distributed Destinations.

On the client side, Queue and Topic objects are handles to the object on the server. Their methods only return their names. To access them for messaging, you create message producers and consumers that attach to them.

A destination supports concurrent use, enabling multiple threads to access the object simultaneously. JMS Queues and Topics extend javax.jms.Destination.

Note: For this release, you can use the JMS Version 1.1 specification destination objects or you can choose to use the subclasses.

The following table describes the Destination subclasses.

Table 2-8 Destination Subclasses Subclass Messaging Model Manages Messages for
Queue PTP JMS point-to-point provider.
TemporaryQueue PTP JMS point-to-point provider, and exists for the duration of the JMS connection in which the messages are created. A temporary queue can be consumed only by the queue connection that created it.
Topic Pub/sub JMS pub/sub provider.
TemporaryTopic Pub/sub JMS pub/sub provider, and exists for the duration of the JMS connection in which the messages are created. A temporary topic can be consumed only by the topic connection that created it.


Note: An application has the option of browsing queues by creating a QueueBrowser object in its queue session. This object produces a snapshot of the messages in the queue at the time the queue browser is created. The application can view the messages in the queue, but the messages are not considered read and are not removed from the queue. For more information about browsing queues, see Setting and Browsing Message Header and Property Fields.

To learn how to use the Destination class within an application, see Developing a Basic JMS Application, or the javax.jms.Destination Javadoc.

Distributed Destinations
A distributed destination resource is a single set of destinations (queues or topics) that are accessible as a single, logical destination to a client (for example, a distributed topic has its own JNDI name). The members of the set are typically distributed across multiple servers within a cluster, with each member belonging to a separate JMS server. Applications that use a distributed destination are more highly available than applications that use standalone destinations because WebLogic JMS provides load balancing and failover for the members of a distributed destination in a cluster.

■For more information on using a distributed destination with your applications, see Using Distributed Destinations.
■For instructions on configuring a distributed queue destination, see “Configure uniform distributed queues” in the Administration Console Online Help.
■For instructions on configuring a distributed topic destination, see “Configure uniform distributed topics” in the Administration Console Online Help.
MessageProducer and MessageConsumer
A MessageProducer sends messages to a queue or topic. A MessageConsumer receives messages from a queue or topic. Message producers and consumers operate independently of one another. Message producers generate and send messages regardless of whether a message consumer has been created and is waiting for a message, and vice versa.

A Session creates the MessageProducers and MessageConsumers that are attached to queues and topics.

The message sender and receiver objects are created as subclasses of the MessageProducer and MessageConsumer classes.

Note: For this release, you can use the JMS Version 1.1 specification message producer and consumer objects or you can choose to use the subclasses.

The following table describes the MessageProducer and MessageConsumer subclasses.

Table 2-9 MessageProducer and MessageConsumer Subclasses Subclass In Messaging Model Performs the Following Function
QueueSender PTP Sends messages for a JMS point-to-point provider.
QueueReceiver PTP Receives messages for a JMS point-to-point provider.
TopicPublisher Pub/sub Sends messages for a JMS pub/sub provider.
TopicSubscriber Pub/sub Receives messages for a JMS pub/sub provider.


The PTP model, as shown in the figure Point-to-Point (PTP) Messaging, allows multiple sessions to receive messages from the same queue. However, a message can only be delivered to one queue receiver. When there are multiple queue receivers, WebLogic JMS defines the next queue receiver that will receive a message on a first-come, first-serve basis.

The pub/sub model, as shown in the figure Publish/Subscribe (Pub/Sub) Messaging, allows messages to be delivered to multiple topic subscribers. Topic subscribers can be durable or non-durable, as described in Setting Up Durable Subscriptions.

An application can use the same JMS connection to both publish and subscribe to a single topic. Because topic messages are delivered to all subscribers, an application can receive messages it has published itself. To prevent clients from receiving messages that they publish, a JMS application can set a noLocal attribute on the topic subscriber, as described in Step 5: Create Message Producers and Message Consumers Using the Session and Destinations.

To learn how to use the MessageProducer and MessageConsumer classes within an application, see Setting Up a JMS Application, or the javax.jms.MessageProducer and javax.jms.MessageConsumer javadocs.

Message
A Message encapsulates the information exchanged by applications. This information includes three components:

■Message Header Fields
■Message Property Fields
■Message Body
Message Header Fields
Every JMS message contains a standard set of header fields that is included by default and available to message consumers. Some fields can be set by the message producers.

For information about setting message header fields, see Setting and Browsing Message Header and Property Fields, or to the javax.jms.Message Javadoc.

The following table describes the fields in the message headers and shows how values are defined for each field.

Table 2-10 Message Header Fields Field Description Defined by
JMSCorrelationID Specifies one of the following: a WebLogic JMSMessageID (described later in this table), an application-specific string, or a byte[] array. The JMSCorrelationID is used to correlate messages and is set directly on the message by the application before send().
There are two common applications for this field.
The first application is to link messages by setting up a request/response scheme, as follows:
1.When an application sends a message, it stores the JMSMessageID value assigned to it.
2.When an application receives the message, it copies the JMSMessageID into the JMSCorrelationID field of a response message that it sends back to the sending application.
The second application is to use the JMSCorrelationID field to carry any String you choose, enabling a series of messages to be linked with some application-determined value. Application
JMSDeliveryMode Specifies PERSISTENT or NON_PERSISTENT messaging. This field is set on the producer or as parameter sent by the application before send().
When a persistent message is sent, it is stored in the WebLogic Persistent Store. The send() operation is not considered successful until delivery of the message can be guaranteed. A persistent message is guaranteed to be delivered at least once.
WebLogic JMS does not store non-persistent messages in the persistent store. This mode of operation provides the lowest overhead. They are guaranteed to be delivered at least once unless there is a system failure, in which case messages may be lost. If a connection is closed or recovered, all non-persistent messages that have not yet been acknowledged will be redelivered. Once a non-persistent message is acknowledged, it will not be redelivered.
This value is overwritten by a call to producer.send(), setting this value directly on the message has no effect. The values set by the producer can be queried using the message supplied to producer.send() or when the message is received by a consumer. send() method
JMSDeliveryTime Defines the earliest absolute time at which a message can be delivered to a consumer. This field is set by the application before send() and depends on timeToDeliver, which is set on the producer.
This field can be used to sort messages in a destination and to select messages. For purposes of data type conversion, the JMSDeliveryTime is a long integer. send() method
JMSDestination Specifies the destination (queue or topic) to which the message is to be delivered. This field is set when creating producer or as parameter sent by the application before send().
This value is overwritten by a call to producer.send(), setting this value directly on the message has no effect. The values set by the producer can be queried using the message supplied to producer.send() or when the message is received by a consumer. When a message is received, its destination value must be equivalent to the value assigned when it was sent. send() method
JMSExpiration Specifies the expiration, or time-to-live value, for a message. This field is set by the application before send(). Depends on timeToLive, which is set on the producer or as a parameter sent by the application to send().
WebLogic JMS calculates the JMSExpiration value as the sum of the application’s time-to-live and the current GMT. If the application specifies time-to-live as 0, JMSExpiration is set to 0, which means the message never expires.
WebLogic JMS removes expired messages from the system to prevent their delivery. send() method
JMSMessageID Contains a string value that uniquely identifies each message sent by a JMS Provider.This field is set internally by send().
All JMSMessageIDs start with an ID: prefix.
This value is overwritten by a call to producer.send(), setting this value directly on the message has no effect. The values set by the producer can be queried using the message supplied to producer.send() or when the message is received by a consumer. When the message is received, it contains a provider-assigned value. send() method
JMSPriority Specifies the priority level. This field is set on the producer or as parameter sent by the application before send().
JMS defines ten priority levels, 0 to 9, 0 being the lowest priority. Levels 0-4 indicate gradations of normal priority, and level 5-9 indicate gradations of expedited priority.
When the message is received, it contains the value specified by the method sending the message.
You can sort destinations by priority by configuring a destination key, as described in “Configure destination keys” in the Administration Console Online Help. send() method
JMSRedelivered Specifies a flag set when a message is redelivered because no acknowledge was received. This flag is of interest to a receiving application.
If set, the flag indicates that JMS may have delivered the message previously because one of the following is true:
■The application has already received the message, but did not acknowledge it.
■The session's recover() method was called to restart the session beginning after the last acknowledged message. For more information about the recover() method, see Recovering Received Messages.
WebLogic JMS
JMSReplyTo Specifies a queue or topic to which reply messages should be sent. This field is set directly on the message by the application before send().
This feature can be used with the JMSCorrelationID header field to coordinate request/response messages.
Simply setting the JMSReplyTo field does not guarantee a response; it simply enables the receiving application to respond. Application
JMSTimestamp Contains the time at which the message was sent. WebLogic JMS writes the timestamp in the message when it accepts the message for delivery, not when the application sends the message.
When the message is received, it contains the timestamp.
The value stored in the field is a Java millis time value. WebLogic JMS
JMSType Specifies the message type identifier (String) set directly on the message by the application before send().
The JMS specification allows some flexibility with this field in order to accommodate diverse JMS providers. Some messaging systems allow application-specific message types to be used. For such systems, the JMSType field could be used to hold a message type ID that provides access to the stored type definitions.
WebLogic JMS does not restrict the use of this field. Application


Message Property Fields
The property fields of a message contain header fields added by the sending application. The properties are standard Java name/value pairs. Property names must conform to the message selector syntax specifications defined in the javax.jms.Message Javadoc. The following values are valid: boolean, byte, double, float, int, long, short, and String.

WebLogic Server supports the use of the following JMS (JMSX) defined properties as defined in the JMS 1.1. Specification:


Table 2-11 JMSX Property Type Description
JMSXUserID System generated property that identifies the user sending the message. See Using the JMSXUserID Property.
JMSXDeliveryCount System generated property that specifies the number of message delivery attempts where first attempt is 1.
JMSXGroupID Identity of the message group.
JMSXGroupSeq Sequence number of a message within a group.


Although message property fields may be used for application-specific purposes, JMS provides them primarily for use in message selectors. You determine how the JMS properties are used in your environment. You may choose to include them in some messages and omit them from others depending upon your processing criteria. For more information, see:

■Setting and Browsing Message Header and Property Fields
■Filtering Messages
■JMS 1.1. Specification
Message Body
A message body contains the content being delivered from producer to consumer.

The following table describes the types of messages defined by JMS. All message types extend javax.jms.Message, which consists of message headers and properties, but no message body.

Table 2-12 JMS Message Types Type Description
javax.jms.BytesMessage Stream of uninterpreted bytes, which must be understood by the sender and receiver. The access methods for this message type are stream-oriented readers and writers based on java.io.DataInputStream and java.io.DataOutputStream.
javax.jms.MapMessage Set of name/value pairs in which the names are strings and the values are Java primitive types. Pairs can be read sequentially or randomly, by specifying a name.
javax.jms.ObjectMessage Single serializable Java object.
javax.jms.StreamMessage Similar to a BytesMessage, except that only Java primitive types are written to or read from the stream.
javax.jms.TextMessage Single String. The TextMessage can also contain XML content.
weblogic.jms.extensions.XMLMessage XML content. Use of the XMLMessage type facilitates message filtering, which is more complex when performed on XML content shipped in a TextMessage.


For more information, see the javax.jms.Message Javadoc. For more information about the access methods and, if applicable, the conversion charts associated with a particular message type, see the Javadoc for that message type.

ServerSessionPoolFactory
Note: Session pool and connection consumer configuration objects are deprecated in this release of WebLogic Server. They are not a required part of the Java EE specification, do not support JTA user transactions, and are largely superseded by message-driven beans (MDBs), which are simpler, easier to manage, and more capable. For more information on designing MDBs, see “Message-Driven EJBs” in Programming WebLogic Enterprise JavaBeans.

A server session pool is a WebLogic-specific JMS feature that enables you to process messages concurrently. A server session pool factory is used to create a server-side ServerSessionPool.

WebLogic JMS defines one ServerSessionPoolFactory object, by default: weblogic.jms.extensions.ServerSessionPoolFactory:, where specifies the name of the JMS server to which the session pool is created. The WebLogic Server adds the default server session pool factory to the JNDI space during startup and the application subsequently retrieves the server session pool factory using WebLogic JNDI.

To learn how to use the server session pool factory within an application, see Defining Server Session Pools, or the weblogic.jms.extnesions.ServerSessionPoolFactory Javadoc.

ServerSessionPool
A ServerSessionPool application server object provides a pool of server sessions that connection consumers can retrieve in order to process messages concurrently.

A ServerSessionPool is created by the ServerSessionPoolFactory object obtained through a JNDI lookup.

To learn how to use the server session pool within an application, see Defining Server Session Pools, or the javax.jms.ServerSessionPool Javadoc.

ServerSession
A ServerSession application server object enables you to associate a thread with a JMS session by providing a context for creating, sending, and receiving messages.

A ServerSession is created by a ServerSessionPool object.

To learn how to use the server session within an application, see Defining Server Session Pools, or the javax.jms.ServerSession Javadoc.

ConnectionConsumer
A ConnectionConsumer object uses a server session to process received messages. If message traffic is heavy, the connection consumer can load each server session with multiple messages to minimize thread context switching.

A ConnectionConsumer is created by a Connection object.

To learn how to use the connection consumers within an application, see Defining Server Session Pools, or the javax.jms.ConnectionConsumer Javadoc.

Note: Connection consumer listeners run on the same JVM as the server.