Skip navigation.

Programming WebLogic JMS

  Previous Next vertical dots separating previous/next from contents/index/pdf Contents View as PDF   Get Adobe Reader

WebLogic JMS C API

The following sections describe how to use the WebLogic JMS C API:


What Is the WebLogic JMS C API?

The WebLogic JMS C API is an application program interface that enables you to create C client applications that can access WebLogic JMS applications and resources. The C client application then uses the Java Native Interface (JNI) to access the client-side Java JMS classes. See Figure 12-1.

For this release, the WebLogic JMS C API adheres to the JMS Version 1.1 specification to promote the porting of Java JMS 1.1 code. For more information, see the WebLogic JMS C API Javadocs


Figure 12-1 WebLogic JMS C API Client Application Environment

WebLogic JMS C API Client Application Environment



System Requirements

The following section provides information on the system requirements needed to use the WebLogic JMS C API in your environment:


WebLogic JMS C API Code Examples

BEA Systems provides samples for JMS developers that illustrate how to configure and develop the WebLogic JMS C API clients. See


Design Principles

The following sections discuss guiding principals for porting or developing applications for the WebLogic JMS C API:

Java Objects Map to Handles

The WebLogic JMS C API is handle-based to promote modular code implementation. This means that in your application, you implement Java objects as handles in C code. The details of how a JMS object is implemented is hidden inside a handle. However, unlike in Java, when you are done with a handle, you must explicitly free it by calling the corresponding Close or Destroy methods. See Memory Allocation and Garbage Collection.

Thread Utilization

The handles returned from the WebLogic JMS C API are as thread safe as their Java counterparts. For example:

As long as concurrency control is managed by the C client application, all objects returned by the WebLogic JMS C API may be used in any thread.

Exception Handling

Note: The WebLogic JMS C API uses integer return codes.

Exceptions in the WebLogic JMS C API are local to a thread of execution. The WebLogic JMS C API has the following exception types:

Type Conversions

When you interoperate between Java code and C code, typically one of the main tasks is converting a C type to a Java type. For example, a short type is a two-byte entity in Java as well as in C. The following type conversions that require special handling:

Integer (int)

Integer (int) converts to JMS32I (4-byte signed value).

Long (long)

Long (long) converts to JMS64I (8-byte signed value).

Character (char)

Character (char) converts to short (2-byte java character).


String converts to JmsString.

Java strings are arrays of two-byte characters. In C, strings are generally arrays of one-byte UTF-8 encoded characters. Pure ASCII strings fit into the UTF-8 specification as well. For more information on UTF-8 string, see It is inconvenient for C programmers to translate all strings into the two-byte Java encoding. The JmsString structure allows C clients to use native strings or Java strings, depending on the requirements of the application.

JmsString supports two kinds of string:

A union of the UNISTRING and CSTRING called uniOrC has a character pointer called string that can be used for a NULL terminated UTF-8 encoded C string. The uniOrC union provides a structure called uniString, which contains a void pointer for the string data and an integer length (bytes).

When the stringType element of JmsString is used as input, you should set it to CSTRING or UNISTRING, depending on the type of string input. The corresponding data field contains the string used as input.

The UNISTRING encoding encodes every two bytes as a single Java character. The two-byte sequence is big-endian. Unicode calls this encoding UTF-16BE (as opposed to UTF-16LE, which is a two-byte sequence that is little-endian). The CSTRING encoding expects a UTF-8 encoded string.

When the stringType element of JmsString is used as output, the caller has the option to let the API allocate enough space for output using malloc, or you can supply the space and have the system copy the returned string into the provided bytes. If the appropriate field in the union (either string or data) is NULL, then the API allocates enough space for the output using malloc. It is the callers responsibility to free this allocated space using free when the memory is no longer in use. If the appropriate field in the union (string or data) is not NULL, then the allocatedSize field of JmsString must contain the number of bytes available to be written.

If there is not enough space in the string to contain the entire output, then allocatedSize sets to the amount of space needed and the API called returns JMS_NEED_SPACE. The appropriate field in the JmsString (either string or data) contains as much data as could be stored up to the allocatedSize bytes. In this case, the NULL character may or may not have been written at the end of the C string data returned. Example:

To allocate one hundred bytes for the string output from a text message, you would set the data pointer and the allocatedSize field to one hundred. The JmsMessageGetTextMessage API returns JMS_NEED_SPACE with allocatedSize set to two hundred. Call realloc on the original string to reset the data pointer and call the function again. Now the call succeeds and you are able to extract the string from the message handle. Alternatively, you can free the original buffer and allocate a new buffer of the correct size.

Memory Allocation and Garbage Collection

All resources that you allocate must also be disposed of it properly. In Java, garbage collection cleans up all objects that are no longer referenced. However, in C, all objects must be explicitly cleaned up. All WebLogic JMS C API handles given to the user must be explicitly destroyed. Notice that some handles have a verb that ends in Close while others end in Destroy. This convention distinguishes between Java objects that have a close method and those that do not. Example:

Note: A handle that has been closed or destroyed should never be referenced again.

Closing Connections

In Java JMS, closing a connection implicitly closes all subordinate sessions, producers, and consumers. In the WebLogic JMS C API, closing a connection does not close any subordinate sessions, producers, or consumers. After a connection is closed, all subordinate handles are no longer available and need to be explicitly closed.

Helper Functions

The WebLogic JMS C API provides some helper functions that do not exist in WebLogic JMS. These helpers are explained fully in the WebLogic JMS C API. For example:

JmsMessageGetSubclass operates on a JmsMessage handle and returns an integer corresponding to the subclass of the message. In JMS, this could be accomplished using instanceof.


Security Considerations

The WebLogic JMS C API supports WebLogic compatibility realm security mode based on a username and password. The username and password must be passed to the initial context in the SECURITY_PRINCIPAL and SECURITY_CREDENTIALS fields of the hash table used to create the InitialContext object.


Implementation Guidelines

Be aware of the following when you implement the WebLogic JMS C API:


Skip navigation bar  Back to Top Previous Next