...
ServiceMix Exec component is used to invoke commands (executables, shell commands, shell scripts, ...). The command can be static (defined in the component endpoint descriptor) or dynamic (provided in the incoming message, including arguments).
Note | ||
---|---|---|
| ||
Note that this component is now only available as snapshot, not yet included in a ServiceMix release. |
Installation
Simply drop the servicemix-exec installer zip in an hotdeploy directory monitored by ServiceMix.
How it works
ServiceMix Exec service engine acts as a provider. It supports all MEP.
When used with an InOnly MEP, the Exec component executes the command and set the exchange in DONE status.
When used with an InOut MEP, the Exec components executes the command and get the command output buffer. The command output is put in the out message and send back in the exchange.
Abstract WSDL
Maven Archetype
The servicemix-exec-service-unit archetype create an Exec Service Unit:
Code Block |
---|
mvn archetype:create \
-DarchetypeGroupId=org.apache.servicemix.tooling \
-DarchetypeArtifactId=servicemix-exec-service-unit \
-DarchetypeVersion=2010.01 \
-DgroupId=your.group.id \
-DartifactId=your.artifact.id \
-Dversion=your-version
|
Endpoint Configuration
The Exec endpoint can be very simple, waiting for command contained in the in message:ServiceMix Exec endpoint exposes an abstract WSDL (in the endpoint descriptor) to define the format of exchanged message.
Code Block | ||||
---|---|---|---|---|
| ||||
<?xml<beans versionxmlns="http://servicemix.apache.org/exec/1.0" xmlns:test="http://test"> <exec:endpoint service="test:MyService" endpoint="MyExec"/> </beans> |
You can define a fallback command if the incoming doesn't provide a command:
Code Block | ||||
---|---|---|---|---|
| ||||
<beans xmlns="http://servicemix.apache.org/exec/1.0"
xmlns:test="http://test">
<exec:endpoint service="test:MyService"
endpoint="MyExec"
command="date"/>
</beans>
|
Info | ||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||
|
How it works
ServiceMix Exec service engine acts as a provider. It supports all MEP.
When used with an InOnly MEP, the Exec component executes the command and set the exchange in DONE status.
When used with an InOut MEP, the Exec components executes the command and get the command output buffer. The command output is put in the out message and send back in the exchange.
Abstract WSDL
ServiceMix Exec endpoint exposes an abstract WSDL (in the endpoint descriptor) to define the format of exchanged message.
Code Block | ||||
---|---|---|---|---|
| ||||
<?xml version="1.0" encoding="UTF-8"?> <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> <wsdl:definitions name="servicemix-exec" targetNamespace="http://servicemix.apache.org/exec" xmlns:tns="http://servicemix.apache.org/exec" xmlns:wsdl='http://schemas.xmlsoap.org/wsdl/' xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <wsdl:types> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" encoding="UTF-8"?> <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> <wsdl:definitions name="servicemix-exec" targetNamespace="http://servicemix.apache.org/exec" xmlns:tns="http://servicemix.apache.org/exec" xmlns:wsdl='http://schemas.xmlsoap.org/wsdl/' xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <wsdl:types> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://servicemix.apache.org/exec" xmlns:tns="http://servicemix.apache.org/exec" attributeFormDefault="unqualified" elementFormDefault="unqualified"> <xs:complexType name="execRequest"> <xs:sequence> <xs:element name="command" type="xs:string" minOccurs="0"/> <xs:element name="arguments" minOccurs="0">targetNamespace="http://servicemix.apache.org/exec" <xs:complexType> xmlns:tns="http://servicemix.apache.org/exec" attributeFormDefault="unqualified" <xs:sequence> elementFormDefault="unqualified"> <xs:complexType name="execRequest"> <xs:element name="argument" type="sequence> <xs:element name="command" type="xs:string" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="arguments" minOccurs="0"> </xs:sequence> <xs:complexType> </xs:complexType> </xs<xs:element>sequence> </xs:sequence> </xs:complexType> <xs:element name="argument" type="xs:string" minOccurs="0" maxOccurs="unbounded"/> <xs:complexType name="execResponse"> <xs</xs:sequence> <xs:element name="endTime" type="xs:long"/> </xs:complexType> <xs:element name="errorData" type="tns:stringBuffer" minOccurs="0"/> </xs:element> </xs:sequence> <xs:element name="executionDuration" type="xs:long"/> </xs:complexType> <xs:elementcomplexType name="exitCode" type="xs:int"/execResponse"> <xs:sequence> <xs:element name="outputData <xs:element name="endTime" type="tnsxs:stringBuffer" minOccurs="0"long"/> <xs:element name="startTimeerrorData" type="xs:longtns:stringBuffer" minOccurs="0"/> </xs:sequence> <xs:element name="executionDuration" type="xs:long"/> </xs:complexType> <xs:complexTypeelement name="stringBufferexitCode" finaltype="extension restriction"xs:int"/> <xs:complexContent> element name="outputData" type="tns:stringBuffer" minOccurs="0"/> <xs:extension baseelement name="startTime" type="tnsxs:abstractStringBuilderlong"/> </xs:sequence> <xs:sequence/> </xs:complexType> <xs:complexType name="stringBuffer" </xs:extension>final="extension restriction"> </xs<xs:complexContent> </xs:complexType> <xs:complexTypeextension namebase="tns:abstractStringBuilder" abstract="true"> <xs:sequence/> </xs:complexType> </xs:schema>extension> </wsdl:types> <wsdl:message name="execRequest"> </xs:complexContent> <wsdl:part name="parameters" element="tns:execRequest"/> </wsdlxs:message>complexType> <wsdl:message name="execResponse"> <wsdl<xs:partcomplexType name="parametersabstractStringBuilder" elementabstract="tns:execResponsetrue"/> </wsdl:message> <wsdl:portType name="ExecPortType"> <wsdl:operation name="execute"<xs:sequence/> <wsdl:input message="tns:execRequest"/></xs:complexType> </xs:schema> <wsdl:output message="tns:execResponse"/> </wsdl:types> <wsdl:message name="execRequest"> </wsdl:operation><wsdl:part name="parameters" element="tns:execRequest"/> </wsdl:portType>message> </wsdl:definitions> |
Note |
---|
It's possible to expose an Exec endpoint directly using a SOAP compliant BC such as ServiceMix HTTP or ServiceMix CXF-BC. |
Note |
---|
An exec endpoint expects an ExecRequest message and provide an ExecResponse. The way to marshal/unmarshal ExecRequest and ExecResponse can be override by defining your own ExecMarshaler. |
ExecRequest
The ExecRequest describes the command to execute with or without arguments. The arguments can be append directly on the command or using the dedicated attributes.
Note |
---|
If the ExecRequest is empty (without command provided), the Exec endpoint will use the static command provided in the xbean.xml (using the command attribute). If no command is provided (neither in the ExecRequest and in the xbean.xml), the Exec endpoint throws an exception and the exchange fails. |
The ExecRequest defines the following attributes:
No Format |
---|
command - the command to execute (for example ls). The command arguments can be provided directly here (for example ls -lt).
arguments - the command arguments.
|
Here is an example of ExecRequest:
...
<?xml version="1.0" encoding="UTF-8"?>
<exec:execRequest xmlns:exec="http://servicemix.apache.org/exec">
<command>ls</command>
<arguments>
<argument>-lt</argument>
<argument>/tmp</argument>
<arguments>
</exec:execRequest>
<wsdl:message name="execResponse">
<wsdl:part name="parameters" element="tns:execResponse"/>
</wsdl:message>
<wsdl:portType name="ExecPortType">
<wsdl:operation name="execute">
<wsdl:input message="tns:execRequest"/>
<wsdl:output message="tns:execResponse"/>
</wsdl:operation>
</wsdl:portType>
</wsdl:definitions>
|
Note |
---|
It's possible to expose an Exec endpoint directly using a SOAP compliant BC such as ServiceMix HTTP or ServiceMix CXF-BC. |
Note |
---|
An exec endpoint expects an ExecRequest message and provide an ExecResponse. The way to marshal/unmarshal ExecRequest and ExecResponse can be override by defining your own ExecMarshaler. |
ExecRequest
The ExecRequest describes the command to execute with or without arguments. The arguments can be append directly on the command or using the dedicated attributes.
Note |
---|
If the ExecRequest is empty (without command provided), the Exec endpoint will use the static command provided in the xbean.xml (using the command attribute). If no command is provided (neither in the ExecRequest and in the xbean.xml), the Exec endpoint throws an exception and the exchange fails. |
The ExecRequest defines the following attributes:
No Format |
---|
command - the command to execute (for example ls). The command arguments can be provided directly here (for example ls -lt).
arguments - the command arguments |
ExecResponse
When used with an InOut MEP, the Exec endpoint returns an ExecResponse. The ExecResponse contains all information about the command execution.
No Format |
---|
started - contains the execution start time in millis (System.currentTimeMillis() is used).
finished - contains the time the process execution finished in millis (System.currentTimeMillis() is used).
duration - the duration in millis the execution took.
exitcode - the return code of the process (0 means all fine; != 0 means an error code).
output - the contents of the output stream of the process.
error - the contents of the error stream of the process.
Some words on the output and error stream contents.
It may happen that some information at the very beginning will get lost depending on how
fast the stream listeners are set up and how fast the executed process will push information to it.
|
Here is an example of an ExecResponseExecRequest:
Code Block | ||||
---|---|---|---|---|
| ||||
<?xml version="1.0" encoding="UTF-8"?> <exec:execResponseexecRequest xmlns:exec="http://servicemix.apache.org/exec"> <started>1241756756376</started> <finished>1241756756390</finished> <duration>14</duration> <exitcode>0</exitcode> <output><![CDATA[ total 6729 -rw------- 1 jb jb 1693752 2009-04-09 09:07 f9G0lWzx.tar.part -rw-r--r-- 1 jb jb 8 2009-03-27 18:27 gnome-session-manager srwxr-xr-x 1 jb jb 0 2009-03-26 10:56 gnome-system-monitor.jb.3619273851 drwxr-xr-x 2 jb jb 1024 2009-04-23 08:43 hsperfdata_jb drwxr-xr-x 2 jboss java 1024 2009-04-17 12:46 hsperfdata_jboss drwxr-xr-x 2 weblogic java 1024 2009-04-17 09:40 hsperfdata_weblogic -rw-r--r-- 1 jb jb 870 2009-03-26 10:59 jbi12672.zip -rw-r--r-- 1 jb jb 870 2009-03-26 10:59 jbi12673.zip ]]></output> <error><![CDATA[ ]]></error> </exec:execResponse> |
Endpoint
The Exec endpoint can be very simple, waiting for command contained in the in message:
<command>ls</command>
<arguments>
<argument>-lt</argument>
<argument>/tmp</argument>
<arguments>
</exec:execRequest>
|
ExecResponse
When used with an InOut MEP, the Exec endpoint returns an ExecResponse. The ExecResponse contains all information about the command execution.
No Format |
---|
started - contains the execution start time in millis (System.currentTimeMillis() is used).
finished - contains the time the process execution finished in millis (System.currentTimeMillis() is used).
duration - the duration in millis the execution took.
exitcode - the return code of the process (0 means all fine; != 0 means an error code).
output - the contents of the output stream of the process.
error - the contents of the error stream of the process.
Some words on the output and error stream contents.
It may happen that some information at the very beginning will get lost depending on how
fast the stream listeners are set up and how fast the executed process will push information to it.
|
Here is an example of an ExecResponse:
Code Block | ||||
---|---|---|---|---|
| ||||
<?xml version="1.0" encoding="UTF-8"?>
<exec:execResponse xmlns:exec="http://servicemix.apache.org/exec">
<started>1241756756376</started>
<finished>1241756756390</finished>
<duration>14</duration>
<exitcode>0</exitcode>
<output><![CDATA[
total 6729
-rw------- 1 jb jb 1693752 2009-04-09 09:07 f9G0lWzx.tar.part
-rw-r--r-- 1 jb jb 8 2009-03-27 18:27 gnome-session-manager
srwxr-xr-x 1 jb jb | ||||
Code Block | ||||
xml | xml | <beans xmlns="http://servicemix.apache.org/exec/1.0" xmlns:test="http://test"> <exec:endpoint service="test:MyService" 0 endpoint="MyExec"/> </beans> |
You can define a fallback command if the incoming doesn't provide a command:
Code Block | ||||
---|---|---|---|---|
xml | xml | <beans xmlns="http://servicemix.apache.org/exec/1.0" 2009-03-26 10:56 gnome-system-monitor.jb.3619273851 drwxr-xr-x 2 jb xmlns:test="http://test"> <exec:endpoint service="test:MyService" jb 1024 2009-04-23 08:43 hsperfdata_jb drwxr-xr-x 2 jboss java 1024 2009-04-17 12:46 hsperfdata_jboss drwxr-xr-x 2 weblogic java 1024 2009-04-17 09:40 hsperfdata_weblogic -rw-r--r-- 1 jb endpoint="MyExec" jb 870 command="date"/> </beans> | ||
Info | ||||
| ||||
Name | Type | Description | Required | |
endpoint | String | JBI Endpoint name | no (will be auto-generated if not specified) | |
interfaceName | QName | Interface QName implemented by the JBI endpoint | no (will be auto-generated if not specified) | |
service | QName | JBI Service name | no (will be auto-generated if not specified) | |
command | String | Fallback command | Command that will be executed if the in message doesn't provide a command. | marshaler | ExecMarshalerSupport | Marshaler to use to parse the incoming message and construct the exec command. | no (DefaultExecMarshaler by default)