Not logged in | Login
Exec BC is used to invoke commands (such as various executables or shell commands) from JBI service units or to poll data by repetitively invoking certain commands (such as "vmstat", "iostat" etc.). Exec BC can invoke commands either locally or remotelly. When the BC is used to invoke a command remotely, SSH2 service must be running on the remote host.
The motivation of creating this BC is based on the demand that occasionally we may want to monitor certain system information in SUs or we may want to invoke something that is only in form of an executable, a system/shell command or maybe just a piece of shell script. Of course we can always do this in a piece of Java code and have JavaEE SE to run it. But it's not so convenient neither elegant. Exec BC makes this job a lot easier.
Following is a simple example that illustrates how Exec BC can be used to poll information on system activities on the local host or a remote host.
Assuming command "vmstat" can be used to retrieve information on system activities. The output of the vmstat command looks like following on Solaris if a polling interval parameter (e.g. 5 seconds) is specified:
kthr memory page disk faults cpu r b w swap free re mf pi po fr de sr cd f0 s0 -- in sy cs us sy id 0 0 0 689444 255612 45 124 102 37 41 0 21 18 0 0 0 828 1319 554 2 14 84 0 0 0 591364 41980 0 14 0 0 0 0 0 0 0 0 0 752 1118 594 1 5 94 0 0 0 591364 41980 0 0 0 0 0 0 0 0 0 0 0 730 1044 565 1 5 94 0 0 0 591364 41980 0 0 0 0 0 0 0 0 0 0 0 752 1169 600 1 5 94 0 0 0 591364 41980 0 0 0 0 0 0 0 0 0 0 0 752 1110 616 1 7 92 0 0 0 591364 41980 0 0 0 0 0 0 0 0 0 0 0 755 1125 587 1 5 94
Would it be nice if each line of the vmstat output can be normalized into a normalized message and be sent to NMR so a BP or an IEP process can do some work on it? Yes, it is possible and easy to do using Exec BC. Basically we just need to create an in-only Exec binding and anwser following questions in the binding section, then Exec BC will poll the data for us.
The above example shows how to use Exec BC to poll system information, which uses the in-only message exchange pattern. In this use case, Exec BC acts as a consumer and messages flow one-way from the BC to NMR continuously. Exec BC also supports other message exchange patterns such as out-in and out-only. In out-in or out-only pattern, Exec BC acts as a provider and can be used to invoke commands programmatically (just like invoking a web service using SOAP/HTTP BC).
The BC repetitively invokes a command, parses the result and sends a message to NMR. Service unit that listens to the endpoint will continuously receive messages.
The BC invokes a command once and keeps reading data from stdout. Once the BC reads enough data to make up a record (based on the defined delimiters), the BC parses the record and sends a message to NMR. Service unit that listens to the endpoint will continuously receive messages.
The BC accepts a message from NMR and constructs a command from the message and the binding information. The command name is always got from the binding information, while the parameter information is got from the message. The BC then invokes the command, reads the result from stdout, parses the result, constructs a response normalized message and send it to NMR.
The BC accepts a message from NMR and constructs a command from the message and the binding information. The command name is always got from the binding information, while the parameter information is got from the message. The BC then invokes the command, discards any data from stdout and set the done flag in the message exchange.
In New WSDL Document wizard, for continuous data polling or out-only command invocation, select One-Way operation, for out-in command invocation, select Request-Response operation. For out-in or out-only command invocation, for the input message type definition, create one part with xsd:string as type. This part will be used to hold command line parameters. For the input message type definition of continuous data polling or the output message type definition of out-in command invocation, set the part to an element with structure and encoding information matching the output data. At Concrete Configuration step, select the EXEC binding type and select the appropriate binding subtype.
In the property view of the exec:operation node, select the appropriate polling pattern and specify the command used to poll data. If the polling pattern is set to RepetitiveInvokeAndReceive, specify a polling interval. If the polling pattern is set to InvokeOnceAndKeepReceiving, property pollingInterval is meaningless and the command being invoked must send data to standard output infinitely, such as vmstat 10. So basically in this polling pattern the interval is controlled by the command itself.
In the property view of the exec:message node, configure following properties:
Specifies whether the data sent to standard output is literal XML or encoded. This property usually should be set to encoded because output of most command invocation is tabular or form style data.
Specifies the encoding style of the data sent to standard output. This property usually should be set to customencoder-1.0 because output of most command invocation is tabular or form style data.
Specifies how many records need to be skipped from the standard output. For example, the standard output of the vmstat command has two column header lines, that may need be skipped before reading the actual record data. This property only makes sense when the value of the delimitersOfRecord property is set. If delimitersOfRecord is not set, all data sent to standard output is considered as one record.
Specifies record delimiters. Once this property is set, it means the data sent to standard output is delimited into records. Multiple delimiters can be specified, in which case, any one of the delimiters can be used to end a record. When specifying multiple delimiters, separate delimiters with a comma, such as "\n,|". '\' (backslash) is used as escape character and following escape sequences are supported:
|\u||Unicode point in hex, no surrogate, must be four characters in length, e.g., \u81EA\u81ED.|
Specifies whether context information should be injected into the data sent to standard output before encoder parses it. Context information is useful when same command is executed on different hosts. In current implementation, context information includes host name and the command being executed. Context information is always delimited using '\n' (line feed) character. For example, for the vmstat command, if this flag is true, the data for the encoder to parse will look like following:
localhost\n vmstat\n kthr memory page disk faults cpu\n r b w swap free re mf pi po fr de sr cd f0 s0 -- in sy cs us sy id\n 0 0 0 689444 255612 45 124 102 37 41 0 21 18 0 0 0 828 1319 554 2 14 84\n ...
Where \n represents a line feed character.
If the output is delimited into records, then context information will be injected into every record if the flag is set to true, as following:
localhost\n vmstat\n 0 0 0 689444 255612 45 124 102 37 41 0 21 18 0 0 0 828 1319 554 2 14 84\n
By default, this flag is set to true.
On the property view of the exec:operation node, set the command to be invoked. Property pollingInterval and pollingPattern are meaningless in this mode and will be ignored.
On the property view of the exec:message node of the input message, set Use to literal. All other properties are meaningless in this mode. If it is out-in command invocation, on the property view of the exec:message node of the output message, configure the properties as described in section Configure Binding Information For Continuous Data Polling.
Additional properties may be introduced later to explicitly specify character encoding setting.
Custom encoder can be used to parse command invocation result. The output resulted from command invocation usually is form or tabular style data, where line feed character usually is the major delimiter and space charatcer is the minor delimiter. Using custom encoder metadata editor (XSD editor plus some extensions), we can define structure that matches the data. Different structures need to be defined for different commands (or for same command but with different parameters). Please see sample metadata and custom encoder to get some ideas on how such metadata can be created. Fields usually are delimited by one or multiple consecutive spaces. For this kind of delimiter, please set both Skip and Collapse properties to true.
Download the sample application that receives vmstat. The sample application demostrates the invoke-once-and-keep-receiving pattern.
|10||29-May-08 10:09 AM, -0700||JunXu||11013||to previous|
|9||08-Oct-07 10:34 AM, -0700||JunXu||10821||to previous | to last|
|8||06-Oct-07 17:36 PM, -0700||JunXu||10750||to previous | to last|
|7||06-Oct-07 01:38 AM, -0700||JunXu||10749||to previous | to last|
|6||06-Oct-07 01:37 AM, -0700||JunXu||10749||to previous | to last|
|5||06-Oct-07 01:08 AM, -0700||JunXu||10683||to previous | to last|
|4||06-Oct-07 00:42 AM, -0700||JunXu||10456||to previous | to last|
|3||05-Oct-07 23:48 PM, -0700||JunXu||10016||to previous | to last|
|2||05-Oct-07 18:14 PM, -0700||JunXu||9840||to previous | to last|
|1||05-Oct-07 18:12 PM, -0700||JunXu||9835||to last|