Creating JMS objects

To create JMS or Jakarta Messaging connection factory and destination objects and store them in a JNDI namespace, use the DEFINE verb. To store your objects in an LDAP environment, you must give them names that comply with certain conventions. The administration tool can help you obey LDAP naming conventions by adding a default prefix to object names.

About this task

The DEFINE verb creates an administered object with the type, name, and properties that you specify. The new object is stored in the current context.

The names of JMS or Jakarta Messaging objects that are stored in an LDAP environment must comply with LDAP naming conventions. One of these conventions is that object and context names must include a prefix, such as cn= (common name), or ou= (organizational unit). The administration tool simplifies the use of LDAP service providers by allowing you to refer to object and context names without a prefix. If you do not supply a prefix, the tool automatically adds a default prefix to the name you supply. For LDAP, this is cn=. If required, you can change the default prefix by setting the NAME_PREFIX property in the configuration file. For more information, see Configuring the JMSAdmin and JMS30Admin tools.

Note: You might need to configure your LDAP server to store Java objects. For more information, see the documentation for your LDAP server.

Procedure

If the administration tool is not already started, start it as described in Starting the JMSAdmin and JMS30Admin tools.
The command prompt is displayed, indicating that the tool is ready to accept administration commands.
Make sure that the command prompt is showing the context in which you want to create the new object.
When you start the administration tool, the prompt initially appears as:
```
InitCtx>
```
To change the current context, use the CHANGE verb as described in Configuring subcontexts.
To create a connection factory, queue destination, or topic destination, use the following command syntax:
```
DEFINE TYPE (name) [property]*
```
That is, type the DEFINE verb, followed by a TYPE (name) administered object reference, followed by zero or more properties (see Properties of IBM MQ classes for JMS objects).
To create a connection factory, queue destination, or topic destination, use the following command syntax:
```
DEFINE TYPE (name) [property]*
```
To display the newly created object, use the DISPLAY verb with the following command syntax:
```
DISPLAY TYPE (name)
```

Example

Example: Creating a queue

The following examples show a queue called testQueue created in the initial context by using the DEFINE verb. Since this object is being stored in an LDAP environment, although the object name testQueue is not entered with a prefix, the tool automatically adds one to ensure compliance with the LDAP naming convention. Submitting the command DISPLAY Q(testQueue) also causes this prefix to be added. [Jakarta Messaging 3.0]


InitCtx> DEFINE Q(testQueue)

InitCtx> DISPLAY CTX

Contents of InitCtx

a cn=testQueue       com.ibm.mq.jakarta.jms.MQQueue

1 Object(s)
0 Context(s)
1 Binding(s), 1 Administered


InitCtx> DEFINE Q(testQueue)

InitCtx> DISPLAY CTX

Contents of InitCtx

a cn=testQueue       com.ibm.mq.jms.MQQueue

1 Object(s)
0 Context(s)
1 Binding(s), 1 Administered

Example: creating a connection factory with JWT token properties

The following examples show a connection factory called CONFACT created in the initial context using the DEFINE verb.

Example that uses the long names of the TOKEN_CLIENT_ID and TOKEN_ENDPOINT properties:

DEFINE CF(CONFACT) HOSTNAME(localhost) PORT(1414) CHANNEL(QM1_SVRCONN) TOKENCLIENTID(MyClientID) 
TOKENENDPOINT(https://keycloak.ibm.com:8080/api/token)

Example that uses the short names of the TOKEN_CLIENT_ID and TOKEN_ENDPOINT properties.

DEFINE CF(CONFACT) HOST(localhost) PORT(1414) HOSTNAME(localhost) PORT(1414) CHANNEL(QM1_SVRCONN) 
TCID(MyClientID) TKEP(https://keycloak.ibm.com:8080/api/token)

As the JMSAdmin or JMS30Admin tool identifies a token endpoint has been provided, it prompts the user to enter the token secret. The console reads the user input with echoing disabled. The token secret is encrypted before it is written to the bindings file.

Note: Since the token secret is a confidential attribute, if it is provided while defining the connection factory properties, the appropriate error is displayed in order to prevent someone from reading the token secret inadvertently.

The following example shows how to display the connection factory properties on the JMSAdmin or JMS30Admin tool:

InitCtx> DISPLAY CF(CONFACT)

    CHANNEL(CHAN1)
    CONNECTIONNAMELIST(9.30.42.223(1513))
    HOSTNAME(9.30.42.223)
    PORT(1513)
    QMANAGER(DEMO)
    TEMPTOPICPREFIX()
    TOKENCLIENTID(jms-client)
    TOKENENDPOINT(https://9.30.42.223:32030/realms/master/protocol/openid-connect/token)
    TOKENSECRET(********)
    TRANSPORT(CLIENT)

InitCtx>

Note: In this example, the TOKEN_CLIENT_SECRET property is shown as asterisk characters (********) because it is confidential.

Example: creating a connection factory when supplying a customized SSLSocketFactory

The following examples show the usage of properties in defining a connection factory called CONFACTJWT or CONFACTCCDTwhen an application supplies a customized SSLSocketFactory when retrieving a JWT or CCDTURL from an HTTPS endpoint.

Example using long and short names of TOKEN_HTTPS_CERT_VALIDATION_POLICY:

DEFINE CF(CONFACTJWT) HOSTNAME(localhost) PORT(1414) CHANNEL(QM1_SVRCONN) TOKENCLIENTID(MyClientID) TOKENENDPOINT(https://keycloak.ibm.com:8080/api/token) TOKENCERTVALPOL(ANY)

DEFINE CF(CONFACTJWT) HOST(localhost) PORT(1414) CHAN(QM1_SVRCONN) TKCD(MyClientID) TKEP(https://keycloak.ibm.com:8080/api/token) TCVP(ANY)

Example using long and short names of WMQ_CCDT_HTTPS_CERT_VALIDATION_POLICY:

DEFINE CF(CONFACTCCDT) CCDTURL(https://ccdturl.com/CCDT.json) QMANAGER(R93) CCDTCERTVALPOL(ANY) TRANSPORT(CLIENT)

DEFINE CF(CONFACTCCDT) CCDT(https://ccdturl.com/CCDT.json) QMGR(R93) CCVP(ANY) TRAN(CLIENT)

For more information, see Supplying a customized SSLSocketFactory in IBM MQ classes for JMS/Jakarta Messaging.