Emit-Event
DESCRIPTION
Causes Info*Engine to send a named event through the Java Messaging Service (JMS) to be handled by any subscribers. When the execution of the webject completes successfully, an empty status group with a status of 0 is returned with a message stating that the event was successfully sent. If the execution of the webject is unsuccessful, an appropriate exception is thrown.
SYNTAX
<ie:webject name="Emit-Event" type="WES">
<ie:param name="DBUSER" data="username"/>
<ie:param name="EVENT" data="my_event"/>
<ie:param name="GROUP_IN" data="group1"/>
<ie:param name="GROUP_OUT" data="results"/>
<ie:param name="PASSWD" data="password"/>
<ie:param name="PRIORITY" data="numeric_value"/>
<ie:param name="PROPERTY" data="name=value"/>
<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="TIME_TO_LIVE" data="minutes"/>
<ie:param name="TYPE" data="[InfoEngine | BytesMessage |
TextMessage | MapMessage | Unknown]"/>
</ie:webject>
PARAMETERS
|
Required
|
Select
|
Optional
|
|
EVENT
|
PUT_BOOLEAN
|
DBUSER
|
|
PUT_BYTE
|
GROUP_IN
|
|
PUT_BYTES
|
GROUP_OUT
|
|
PUT_CHAR
|
PASSWD
|
|
PUT_DOUBLE
|
PRIORITY
|
|
PUT_FLOAT
|
PROPERTY
|
|
PUT_INT
|
TIME_TO_LIVE
|
|
PUT_LONG
|
SERVICE
|
|
PUT_SHORT
|
|
|
PUT_STRING
|
|
|
TYPE
|
|
DBUSER
Specifies 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
.wes.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 Web Event Service (WES) 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 .wes.username property is used. If the .wes.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.
EVENT
Specifies the LDAP distinguished name of the event to emit. The value is an LDAP distinguished name relative to a configured base URI. A syntax of <event_name>@<domain> is recommended to give additional meaning and avoid name conflicts. If relative, the cn= (common name attribute) is implicit if not explicitly specified.
This parameter is required.
GROUP_IN
Specifies the name of a group to be sent along with the event. This parameter should only be specified if the TYPE is InfoEngine. If GROUP_IN is specified and the TYPE is set to a different value, then GROUP_IN is ignored.
Multiple GROUP_IN values may be specified. A value of “*” causes the entire VDB to be sent. The default for this parameter is to send an empty VDB collection.
This parameter is optional.
GROUP_OUT
Specifies the name of the status group to create upon success. The default for this parameter is to create a group named emit-results.
This parameter is optional.
PASSWD
Specifies 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
.wes.password and
.jms.password properties of the service that is used to connect to the MOM. For more information about credentials mapping, see
Credentials Mapping.
If this parameter is omitted, the mapped credentials for the Web Event Service (WES) 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 .wes.password property is used. If the .wes.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.
TIME_TO_LIVE
Specifies in minutes how long the event should be valid. The default value for this parameter is 0, which is a special case indicating that the message does not expire.
This parameter is optional.
SERVICE
Specifies 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.
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 events sent 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.
The default behavior for this parameter is to not 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 may be specified as True or False. This parameter can only be used if the TYPE is specified as BytesMessage or MapMessage.
PUT_BYTE
Places a single byte into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage or MapMessage.
PUT_BYTES
Places multiple bytes into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage or MapMessage.
PUT_CHAR
Places a single Java character into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage or MapMessage.
PUT_DOUBLE
Places a Java double value into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage or MapMessage.
PUT_FLOAT
Places a floating point number into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage or MapMessage.
PUT_INT
Places an integer into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage or MapMessage.
PUT_LONG
Places a long integer into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage or MapMessage.
PUT_SHORT
Places a short integer into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage or MapMessage.
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, or MapMessage.
TYPE
Specifies the type of message to be sent by selecting the processor used to generate the outgoing message. Message types are case-sensitive.
The default value for this parameter is InfoEngine, which means 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).
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 may 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, where name is the key used to place data in the MapMessage.
◦ Unknown—Turns BLOB data into a BytesMessage. For incoming messages, a new, empty Info*Engine request is created and the contents of the message are attached as BLOB data.
The following table indicates which PUT_type parameters can be specified with which message types:
|
BytesMessage
|
TextMessage
|
MapMessage
|
|
PUT_BOOLEAN
|
X
|
|
X
|
|
PUT_BYTE
|
X
|
|
X
|
|
PUT_BYTES
|
X
|
|
X
|
|
PUT_CHAR
|
X
|
|
X
|
|
PUT_DOUBLE
|
X
|
|
X
|
|
PUT_FLOAT
|
X
|
|
X
|
|
PUT_INT
|
X
|
|
X
|
|
PUT_LONG
|
X
|
|
X
|
|
PUT_SHORT
|
X
|
|
X
|
|
PUT_STRING
|
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.
|
EXAMPLE
The following example emits a specified event to be handled by any subscribers:
<%@page language="java" session="false"%>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie"%>
<ie:webject name="Emit-Event" type="WES">
<ie:param name="DBUSER" data="$(@FORM[]dbuser[])"/>
<ie:param name="PASSWD" data="$(@FORM[]passwd[])"/>
<ie:param name="GROUP_IN" data="$(@FORM[]group_in[])"/>
<ie:param name="GROUP_OUT" data="$(@FORM[]group_out[])"/>
<ie:param name="EVENT" data="$(@FORM[]event[])"/>
<ie:param name="TIME_TO_LIVE" data="0"/>
<ie:param name="PRIORITY" data="$(@FORM[]priority[])"/>
</ie:webject>
To actually run this example, you need to provide a form where the DBUSER, PASSWD, GROUP_IN, GROUP_OUT, EVENT, and PRIORITY variables are identified.
