Uploading files to multiple registered hosts with a single REST call
You can upload files from a collective controller to multiple registered hosts of a collective by invoking the POST REST API. The file transfer operations occur within an IBM JMX REST Connector.
Before you begin
Create a collective controller.
Register each remote host computer with the collective controller.
Procedure
- Optional:
To read about the REST APIs, point a browser at
https://controller_host_name:controller_port_name/IBMJMXConnectorREST/api
and enter the controller administrative user ID and password to log in. The controller must be
running to view the REST API documentation.
The File Transfer and Routing sections describe the APIs used to transfer files between the collective controller and a member server or a registered host.
The
collectiveController-1.0
feature enables therestConnector-1.0
feature, which provides file transfer capability. Thus, collective controllers do not need to specifyrestConnector-1.0
in a feature manager to view the REST APIs or perform file transfer operations. A stand-alone server configuration might need therestConnector-1.0
feature to view the REST APIs. TherestConnector-2.0
feature is tolerated. -
List the target hosts in an HTTP header for the collective controller.
com.ibm.websphere.collective.hostNames=comma-separated_list_of_target_hosts
Optionally, set other HTTP headers:
- Specify whether to perform the file uploads and the action asynchronously. Default is
false
. To change the default, specifytrue
for boolean.com.ibm.websphere.jmx.connector.rest.asyncExecution=boolean
- Specify a set of actions to perform after the file uploads. An existing built-in action is
com.ibm.websphere.jmx.connector.rest.postTransferAction.join
, which joins the Liberty servers inside the incoming Liberty archive to the collective. Use the header to list other custom actions. If you list more than one custom action, delimit the action with a URL-encoded comma character.com.ibm.websphere.jmx.connector.rest.postTransferAction=comma-separated_list_of_actions
To enable the custom actions, add the following configuration to the collective controller server.xml:<hostAccess enableCustomActions="true" />
- Specify a list of options to pass into the post-transfer actions. This list of options must be
either null or contain the same number of list items as the
postTransferAction
header list, where the item index of each option must match the index of its corresponding action. If you list more than one option, delimit the action with a URL-encoded comma character.com.ibm.websphere.jmx.connector.rest.postTransferAction.options=comma-separated_list_of_options
If you specify the built-in action
com.ibm.websphere.jmx.connector.rest.postTransferAction.join
, the corresponding option must be:--user=adminUser --password=adminPw --keystorePassword=keystorePw [--rpcUser=rpcUser --rpcPassword=rpcPw]
- Specify environment variables to set before the transfer actions run. The payload of the header
is a JSON object where each JSON key is an environment variable and each JSON value is its
corresponding value. If you specify system paths, use forward slashes
(
/
).com.ibm.websphere.jmx.connector.rest.transferEnvVars=list_of_environment_variables
- Specify whether to perform the file uploads and the action asynchronously. Default is
-
Upload a file to multiple registered hosts by using the POST
operation.
- Ensure that the target location is within a configurable write directory of the hosts.
- Invoke the POST
operation.
POST https://controller_host:controller_port/IBMJMXConnectorREST/file/{filePath}[?expandOnCompletion=boolean&local=boolean]
{filePath}
is a UTF-8 URL-encoded absolute path that specifies the target location. For example, if the file is C:/temp/myFile.txt, the path is C%3A%2Ftemp%2FmyFile.txt.expandOnCompletion
is an optional query parameter that toggles an automatic expansion of the uploaded archive. The default value isfalse
.local
is an optional query parameter that specifies whether the file to upload is already in the controller. If true, then the payload of this POST request is a string that represents the source file location inside the controller. The default value isfalse
.- If the
local
query parameter is not used, or explicitly set to false, the POST payload is the binary content of the source file itself.
What to do next
Get status or details on the REST call. See Getting status on a REST call for multiple registered hosts.