15-4 Programming JMS for Oracle WebLogic Server
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.
15.3.5 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:
■
The javax.jms.Session object has a close method so the WebLogic JMS C API has a JmsSessionClose function.
■
The javax.jms.ConnectionFactory object does not have a close method so the WebLogic JMS C API has a JmsConnectionFactoryDestroy function.
15.3.6 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.
Note: A handle that has been closed or destroyed should never be
referenced again.
WebLogic JMS C API 15-5
15.3.7 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 Oracle WebLogic Server JMS C
API Reference. 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.
15.4 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.
15.5 Implementation Guidelines
Be aware of the following when you implement the WebLogic JMS C API:
■
It does not support WebLogic Server JMS extensions, including XML messages.
■
It does not support JMS Object messages.
■
It creates an error log if an error is detected in the client. This error log is named ULOG.mmddyy monthdayyear. This log file is fully internationalized using the
NLSPATH, LOCALE, and LANG environment variables of the client.
■
Users who want to translate the message catalog can use the gencat utility provided on Windows or the gencat utility of the host platform. If the generated
catalog file is placed according to the NLSPATH, LOCALE, and LANG variables, then the translated catalog will be used when writing messages to the log file.
■
You can set the following environment variables in the client environment:
– JMSDEBUG— Provides verbose debugging output from the client.
– JMSJVMOPTS
—Provides extra arguments to the JVM loaded by the client.
– ULOGPFX— Configures the pathname and file prefix where the error log file is
placed.
15.6 Workarounds for Client Crash Thread Detach Issue
A C program that uses the JMS C client library may crash with a JVM failure. This could be related to a known, intermittent race-condition that occurs only with certain
JVM products. The likelihood of failure can change based on the JVM version and patch level, operating system, and hardware combination. Specifically, the JMS
C-Client library implicitly attaches C-threads to the JVM, but fails to detach them when it is done with them. Suggested workarounds are as follows:
■
Upgrade to a newer JVM. Version 1.5 and later of the Sun JVM, and version R27.6 of the JRockit JVM do not have this problem, although it is still recommended to
call detach even with the updated JVMs. For more information about this issue with the Sun JVM, see
http:bugs.sun.combugdatabaseview_ bug.do?bug_id=6219874
.
■
Add code in the client to detach the JVM from any C thread that exits and that has previously called into the JMS C-API.
