API Web Services

2.1 Operations

The Oracle Virtual Assembly Builder Deployer provides logical operations which are used in the Web service and CLI operations. Some operations are asynchronous and the status of these operations can be tracked with a describeRequests operation.

The complete API reference for the operations are described in the following chapters:

2.2 Administrative Operations

Oracle Virtual Assembly Builder Deployer provides logical administrative operations for configuring targets, which reference pools in virtualization environments. All of these operations are synchronous.

Due to the differences in how virtualization environments work and how we interact with them, configuration of these involves two steps.

Creating targets using the CreateTarget operation. This step is only required for Oracle VM, because Oracle Exalogic comes with a single pre-configured target.
Adding user configuration information for a named user to a target using AddTargetUser. For more details, see Section 3.3, "AddTargetUser" in Chapter 3, "API Reference: Administrative Operations".

Operations for adding users are not provided in these administrative operations. It is intended that these operations be performed directly against the LDAP server by security administrators authorized for such duties.

2.3 Usage and Lifecycle

The first operation when using the Oracle Virtual Assembly Builder Deployer is to upload an assembly archive to the Deployer's repository using the uploadAssemblyArchive operation.

You can register the uploaded assembly archive with one or more targets using the registerAssemblyArchive operation. The details of registration are specific to the target type. For Oracle VM, registration includes uploading the assembly archive to the Deployer and registering the templates with a target within the Oracle VM system.

After an assembly archive has been registered with a target, you can create one or more assembly instances for that registration using the createAssemblyInstance operation. An assembly instance is a context used to manage the lifecycle of VM instances for the assembly defined by the assembly archive. When creating an assembly instance, a deployment plan must be provided which defines the environment-specific details of the assembly managed through the assembly instance.

Once an assembly instance has been created for an assembly archive, you can initiate a deployment operation. During deployment, the initial instances for the assembly defined by the assembly archive are created and started. As this is done, the Deployer interacts with reconfiguration logic embedded in the initialization scripts of the instances which configures networks and mounted disk volumes and also configures the application stack for the environment. These interactions configure connections between instances that are created when the application stack starts up.

Once an assembly instance has been deployed, a number of other lifecycle operations can be applied to the running system such as scale which increases or decreases the number of running instances for an appliance within the assembly. There are also operations to stop and start all instances of the deployment, which are used for bringing the application offline and back online.

2.4 Admin Web Service

Operations against the Web service are made by posting an HTTP request to the Deployer's context path. The request includes a request parameter that defines the action followed by zero or more request parameters that define arguments for the operation. See Section 2.5.2, "Query String Pattern" below for more details.

2.4.1 Context Path

The context path for the admin Web service is /ovab/admin.

2.4.2 Query String Pattern

Action= action&param1=value&param2=value...

For an array of values, use the same parameter name multiple times in the query string. For example:

Action= action&param1=value&param2=value&param2=value...

2.4.3 Actions

Chapter 3, "API Reference: Administrative Operations"describes all of the operations exposed by the admin Web service. Details of the types included in the "Response Content" column may be found in the schema in Appendix A, "Web Service Schema".

2.4.4 Error Handling

Table 2-1 shows how error handling is performed for the Web service.

Table 2-1 Web Service Error Handling

Responsible for Error	HTTP Status Code	Response Content XML Element
User	4xx	ErrorResult (type=USER)
Service	5xx	ErrorResult (type=SERVICE)

Note:

In the case of an error, there may not be any content (ErrorResult) in the response. If the HTTP status code is generated by the servlet container, then there will not be any content in response. If the HTTP response is generated by the Oracle Virtual Assembly Builder Deployer, then most often there will be content in response, except when an unexpected service error occurs.

2.4.5 XML Schema

You can find the schema for the Web service in Appendix A, "Web Service Schema". This schema includes definitions for the response content items included in the table of actions, above.

2.5 Deployer Web Service

Operations against the Web service are made by posting an HTTP request to the Deployer's context path. The request includes a request parameter that defines the action followed by zero or more request parameters that define arguments for the operation. See Section 2.5.2, "Query String Pattern" below for more details.

As described in Section 2.1, "Operations", some operations may initiate an asynchronous action. The operations exposed by the Web service are the same as is described for the logical operations described earlier.

2.5.1 Context Path

The context path for the Deployer Web service is /ovab/deployer.

2.5.2 Query String Pattern