Skip Headers
Oracle® Virtual Assembly Builder Developer's Guide
11g Release 1 (11.1.1.6)

Part Number E26204-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

2 API Web Services

The following sections describes the Oracle Virtual Assembly Builder Web Service API:

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.

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

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.5.3 Actions

Chapter 4, "API Reference: Deployer Operations" describes all of the operations exposed by the Deployer 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.5.4 Error Handling

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

Table 2-2 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.5.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.