Create-Object
Creates a JMS message and places that message in a JMS message queue. The type and contents of the message are governed by its parameters.
|
|
This webject can be used only after your environment has been set up for messaging.
|
SYNTAX
<ie:webject name="Create-Object" type="MSG">
<ie:param name="DBUSER" data="username"/>
<ie:param name="GROUP_IN" data ="group_name"/>
<ie:param name="GROUP_OUT" data ="status_group_name"/>
<ie:param name="PASSWD" data="password"/>
<ie:param name="PRIORITY" data ="numeric_value"/>
<ie:param name="PROPERTY" data ="name_value_pair"/>
<ie:param name="PUT_BOOLEAN" data ="[TRUE | FALSE]"/>
<ie:param name="PUT_BYTE" data ="byte"/>
<ie:param name="PUT_BYTES" data ="bytes"/>
<ie:param name="PUT_CHAR" data ="char"/>
<ie:param name="PUT_DOUBLE" data ="double"/>
<ie:param name="PUT_FLOAT" data ="float"/>
<ie:param name="PUT_INT" data ="int"/>
<ie:param name="PUT_LONG" data ="long"/>
<ie:param name="PUT_SHORT" data ="short"/>
<ie:param name="PUT_STRING" data ="string"/>
<ie:param name="QUEUE" data ="managed_queue_name"/>
<ie:param name="TIME_TO_LIVE" data="minutes"/>
<ie:param name="TYPE" data ="message_type"/>
</ie:webject>
PARAMETERS
|
Required
|
Select
|
Optional
|
|
QUEUE
|
PUT_BOOLEAN
|
DBUSER
|
|
PUT_BYTE
|
GROUP_IN
|
|
PUT_BYTES
|
GROUP_OUT
|
|
PUT_INT
|
PASSWD
|
|
PUT_CHAR
|
PRIORITY
|
|
PUT_DOUBLE
|
PROPERTY
|
|
PUT_FLOAT
|
TIME_TO_LIVE
|
|
PUT_LONG
|
SERVICE
|
|
PUT_SHORT
|
|
|
PUT_STRING
|
|
|
TYPE
|
|
DBUSER
The username to use when connecting to the MOM. If this parameter is specified, the parameter value takes precedence over any existing credentials mapping for the authenticated user, or any value specified in the
.msg.username and
.jms.username properties of the service that is used to connect to the MOM. For more information, see
Credentials Mapping for MOMs.
If this parameter is omitted, the mapped credentials for the Info*Engine messaging software are used. If no such mapping is found, then the mapped credentials for the Java Messaging Service (JMS) are used. If neither of these mapped credentials are found, then the value set in the .msg.username property is used. If the .msg.username property is not set, then the value set in the .jms.username property is used. If neither property is set and you do not specify a value for this DBUSER parameter, Info*Engine does not specify a username when connecting to the MOM, and an anonymous connection is attempted.
This parameter is optional.
GROUP_IN
The name of an Info*Engine group to serialize with the request. A value of “*” means serialize all groups. This parameter only makes sense if the TYPE parameter is Info*Engine. This parameter is optional.
GROUP_OUT
The name of the status group to create upon success. The default for this parameter is to created a group named “create-results”. This parameter is optional.
PASSWD
The password to use when connecting to the MOM. If this parameter is specified, the parameter value takes precedence over existing credentials mapping for the authenticated user, or any value specified in the
.msg.password and
.jms.password properties of the service that is used to connect to the MOM. For more information, see
Credentials Mapping for MOMs.
If this parameter is omitted, the mapped credentials for the Info*Engine messaging software are used. If no such mapping is found, then the mapped credentials for the Java Messaging Service (JMS) are used. If neither such mapped credentials are found, then the value set in the.msg.password property is used. If the .msg.password property is not set, then the value set in the .jms.password property is used. If neither property is set and you do not specify a value for this PASSWD parameter, Info*Engine does not specify a password when connecting to the MOM. This parameter is optional.
PRIORITY
Specifies an integer priority to be set on the outgoing messages. The valid range for JMS Queue priorities is from 0 – 9, with 4 the typical default value. Priorities are ignored by Info*Engine, but can be used by third-party software receiving messages queued by Info*Engine. This parameter is optional.
PROPERTY
Specifies a name and value pair to set on the outgoing JMS message. These properties are ignored by Info*Engine, but can be used by third-party software. The format for the PROPERTY value is:
name=value
where:
◦ name—The property name.
◦ value—The corresponding value of the property.
This default behavior for this parameter is not to set any additional properties on the outgoing message. This parameter is optional.
PUT_BOOLEAN
Places a Java Boolean value into the JMS message. The value can be specified as TRUE or FALSE. This parameter can only be used if the TYPE is specified as BytesMessage, MapMessage, or StreamMessage.
PUT_BYTE
Places a single byte into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage, MapMessage, or StreamMessage.
PUT_BYTES
Places multiple bytes into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage, MapMessage, or StreamMessage.
PUT_CHAR
Places a single Java character into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage, MapMessage, or StreamMessage.
PUT_DOUBLE
Places a Java double value into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage, MapMessage, or StreamMessage.
PUT_FLOAT
Places a floating point number into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage, MapMessage, or StreamMessage.
PUT_INT
Places an integer into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage, MapMessage, or StreamMessage.
PUT_LONG
Places a long integer into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage, MapMessage, or StreamMessage.
PUT_SHORT
Places a short integer into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage, MapMessage, or StreamMessage.
PUT_STRING
Places an instance of java.lang.String into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage, TextMessage, MapMessage, or StreamMessage.
QUEUE
The LDAP relative distinguished name of the JMS Queue to which to submit the new message. The value is an LDAP distinguished name relative to a configured base URI. If relative, the cn= (common name attribute) is implicit if not explicitly specified. This parameter is required.
TIME_TO_LIVE
Specifies how long, in minutes, the queued message should be valid. The default for this parameter is 0, in which case the message remains valid indefinitely. This parameter is optional.
SERVICE
The name of the Info*Engine property set that is configured for connectivity to a specific JMS service. This allows you to configure more than one JMS service per Info*Engine Virtual Machine (VM). This parameter is optional.
TYPE
Indicates the type of JMS message to create. Message types are case-sensitive. Possible message types are:
◦ InfoEngine—Used for Info*Engine to Info*Engine communication. VDB groups serialized are governed by the GROUP_IN parameter.
◦ BytesMessage—For outgoing messages, this type supports several PUT_type parameters for building a message that might be specific to a third-party recipient. Incoming messages are processed in the same manner as Unknown. The contents of a BytesMessage is supplied as BLOB data on an input stream to the calling task.
◦ TextMessage—Supports only a PUT_STRING parameter. Multiple PUT_STRING parameter values are concatenated together to create the outgoing TextMessage.
◦ MapMessage—For outgoing messages, this type supports several PUT_type parameters with values in the form of name=data. The name portion of the value is the key used to place data in the MapMessage.
◦ StreamMessage—For outgoing messages, this type supports several PUT_type parameters for building a message that might be specific to a third-party recipient.
◦ Unknown—Turns BLOB data into a BytesMessage. For incoming messages, a new empty IeRequest is created and the contents of the message are tacked on as BLOB data.
The following table indicates which PUT_type parameters can be specified with which message types:
|
BytesMessage
|
TextMessage
|
MapMessage
|
StreamMessage
|
|
PUT_BOOLEAN
|
X
|
|
X
|
X
|
|
PUT_BYTE
|
X
|
|
X
|
X
|
|
PUT_BYTES
|
X
|
|
X
|
X
|
|
PUT_CHAR
|
X
|
|
X
|
X
|
|
PUT_DOUBLE
|
X
|
|
X
|
X
|
|
PUT_FLOAT
|
X
|
|
X
|
X
|
|
PUT_INT
|
X
|
|
X
|
X
|
|
PUT_LONG
|
X
|
|
X
|
X
|
|
PUT_SHORT
|
X
|
|
X
|
X
|
|
PUT_STRING
|
X
|
X
|
X
|
X
|
|
|
Support for the type STRING in BytesMessage actually causes the value of the string to be written as a byte array; it is not actually written as a string.
|
The default value for this parameter is InfoEngine, meaning that an Info*Engine request is serialized and placed in the queue. “Serialized” in this case can mean actual Java serialization or serialization of an Info*Engine request to XML (this is the case when BLOB data needs to be queued as well).
EXAMPLES
The following example creates a JMS message and submits it to the specified queue:
<%@page language="java" session="false"%>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie"%>
<ie:webject name="Create-Object" type="MSG">
<ie:param name="DBUSER" data="$(@FORM[]dbuser[])"/>
<ie:param name="PASSWD" data="$(@FORM[]passwd[])"/>
<ie:param name="QUEUE" data="$(@FORM[]queue[])"/>
<ie:param name="TIME_TO_LIVE" data="$(@FORM[]time[])"/>
<ie:param name="PRIORITY" data="$(@FORM[]priority[])"/>
<ie:param name="TYPE" data="TextMessage"/>
<ie:param name="PUT_STRING" data="$(@FORM[]string[])"/>
<ie:param name="GROUP_OUT" data="results"/>
</ie:webject>
To actually run this example you must provide a form where the dbuser, passwd, queue, time, priority, and string variables are identified.
The following example shows how the Create-Object webject could be used to queue a TextMessage containing XML data to be processed by a third-party application:
<%@page language="java"%>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core" prefix="ie"%>
<!-- get an "employee object from JDBC/JNDI or where ever,
for the purposes of example just using Create-Group -->
<ie:webject name="Create-Group" type="GRP">
<ie:param name="ELEMENT"
data="name=joe:email=joe@somewhere.nice"/>
<ie:param name="ELEMENT" data="name=bob:email=bob@nowhere.net"/>
<ie:param name="GROUP_OUT" data="employees"/>
</ie:webject>
<!-- xml-ize the parts -->
<ie:webject name="Format-Group" type="GRP">
<ie:param name="GROUP_IN" data="employees" />
<ie:param name="GROUP_OUT" data="formatted"/>
<ie:param name="ATTRIBUTE" data="name"/>
<ie:param name="ATTRIBUTE" data="email"/>
<ie:param name="FORMAT"
data="<employee><name>{0}</name><email>{1}</email></employee>"/>
</ie:webject>
<!-- turn them into an XML document and put in in a TextMessage on
my queue -->
<ie:webject name="Create-Object" type="MSG">
<ie:param name="PUT_STRING" data="<?xml version='1.0'> "/>
<ie:param name="PUT_STRING" data="<employees> "/>
<ie:param name="PUT_STRING"
data="$(formatted[*]nameemail[0]) "
valueSeparator=";" delim=";" />
<ie:param name="PUT_STRING" data="</employees> "/>
<ie:param name="TYPE" data="TextMessage"/>
<ie:param name="QUEUE" data="cn=The.Q"/>
</ie:webject>
