WebLogic JMS C API 15-3
■
java.jms.Connection objects are thread safe, and the corresponding WebLogic JMS C API handle, JmsConnection, is thread safe.
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.
15.3.3 Exception Handling
Exceptions in the WebLogic JMS C API are local to a thread of execution. The WebLogic JMS C API has the following exception types:
■
JavaThrowable represents the class java.lang.Throwable.
■
JavaException represents the class java.lang.Exception.
■
JmsException represents the class javax.jms.JMSException. All standard subclasses of JMSException are determined by bits in the type descriptor of the
exception. The type descriptor is returned with a call to JmsGetLastException.
15.3.4 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:
15.3.4.1 Integer int
Integer int converts to JMS32I 4-byte signed value.
15.3.4.2 Long long
Long long converts to JMS64I 8-byte signed value.
15.3.4.3 Character char
Character char converts to short 2-byte java character.
15.3.4.4 String
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
http:www.unicode.org . 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:
■
Native C string CSTRING
■
JavaString UNISTRING 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.
Note: The WebLogic JMS C API uses integer return codes.
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
