Web Services clients

The SA API supports Web Services, a programming environment built on open industry standards such

as SOAP (Simple Object Access Protocol) and WSDL (Web Services Definition Language). You can create Web Services clients in a variety of programming languages such as Perl and C# (as shown later in this section) or with Web Services-enabled development environments such as Microsoft Visual Studio .NET.

This topic is intended for software developers who are familiar with SA fundamentals and Web Services development.

• Programming language bindings provided in this release
• URLs for service locations and WSDLs
• Security for Web Services clients
• Overloaded operations
• Java interface support
• Unsupported data types
• Invoke setDirtyAtrributes when creating or updating VOs
• Compatibility with SA Web Services API 2.2

Programming language bindings provided in this release

This release of SA includes Web Services client stubs for C#. Web Services clients written in Perl do not require client stubs.

This release does not include Web Services client stubs for Java or Python. However, Java clients can access the SA API through RMI and Python clients through Pytwist, as described in the preceding sections.

URLs for service locations and WSDLs

Clients access the Web Services at URLs with the following syntax, where host is the server running the OCC core component and port is for the HTTPS proxy. (The default proxy port is 443). The packageName corresponds to the Java library that the service belongs to.

https://host:port/osapi/packageName/WebServiceName

The WSDL files are at URLs with the following syntax:

https://host:port/osapi/packageName/WebServiceName?WSDL

For example, the following URLs point to the FolderService location and WSDL:

https://occ.c38.example.com:443/osapi/com/opsware/folder/FolderService

https://occ.c39.example.com:443/osapi/com/opsware/folder/FolderService?wsdl

The SOAP binding style is RPC (Remote Procedure Call) and the transport protocol is HTTPS.

Security for Web Services clients

Like other clients of the SA API, Web Services clients must be authenticated and authorized to perform operations in SA. Communication between clients and the Web Services component in the SA core is encrypted. Access is restricted to HTTPS clients through the HTTPS proxy port of the OCC core component. (The default port is 443.)

Overloaded operations

The SA API has overloaded operations, but the WSDL 2.0 specifications do not support overloading. An overloaded operation in the SA API is exposed by the Web Service as a single operation.

Java interface support

The SA API uses Java interfaces, but Web Services does not support interfaces. As a workaround, the WSDL files map interfaces to xsd:anyType. For clients coded in object-oriented programming languages such as C#, if an API method returns an interface, the return type must be cast to a concrete class. Arrays of interfaces are converted to Object[]; specific types of the array members are preserved through serialization/deserialization. For a C# code example, see Handle interface return types.

Unsupported data types

The following data types are used by the SA API but are not supported by SOAP:

java.util.Properties
com.opsware.common.ModifiableMap
com.opsware.acm.ValueSet
com.opsware.swmgmt.PolicyOverrideFilter

Methods omitted from Web Services

The following SA API methods use unsupported data types as parameters or return types. As a result, they are not exposed as operations in the Web Services.

com.opsware.custattr.CustomAttribute.getCustAttrs
com.opsware.custattr.CustomAttribute.setCustAttrs
com.opsware.custattr.CustomField.getCustomFields
com.opsware.custattr.CustomField.setCustomFields
com.opsware.pkg.Patch.getPolicyOverrideRefs

Partial support for java.util.Map

Axis converts java.util.Map to apachesoap:Map, which is a collection of key-value pairs. With .NET, this conversion does not work. C# clients, for example, will receive an empty array of key-value pairs. However, this conversion does work with Soap::Lite in Perl. Therefore, SA API methods that use java.util.Map are available as operations in the Web Services.

The following methods use java.util.Map as parameters or return types:

com.opsware.acm.GroupConfigurable.getApplicationInstances
com.opsware.acm.ServerConfigurable.getCustAttrsWithRC
com.opsware.compliance.sco.CMLSnapshot.getValueSet
com.opsware.compliance.sco.CMLSnapshot.setValueSet
com.opsware.compliance.sco.SnapshotResultService.remediateCMLSnapshot
com.opsware.custattr.VirtualColumnVO.getConfigInfo
com.opsware.custattr.VirtualColumnVO.setConfigInfo

Methods in VOs with unsupported data types

The following methods of VOs use unsupported data types as parameters or return types:

com.opsware.acm.ApplicationInstanceVO.getValueset
com.opsware.acm.ApplicationInstanceVO.setValueset
com.opsware.acm.ConfigurableVO.getValueset
com.opsware.acm.ConfigurableVO.setValueset
com.opsware.virtualization.VirtualConfigNode.getProperties
com.opsware.virtualization.VirtualConfigNode.setProperties
com.opsware.virtualization.VirtualServerConfig.getProperties
com.opsware.virtualization.VirtualServerConfig.setProperties

Invoke setDirtyAtrributes when creating or updating VOs

Web Services clients must invoke setDirtyAttributes before invoking a create or update method on a service. The setDirtyAttributes method explicitly the marks the attributes (fields) of a VO that need to be set by the create or update invocation. The attribute names specified by setDirtyAttributes are case sensitive.

For example, to modify the description attribute of a FolderVO object, the following code invokes setDirtyAttributes before it invokes update:

// fs is FolderService
FolderVO folderVO = fs.getFolderVO(folderRef);
folderVO.setDescription("credit card processing");
folderVO.setDirtyAttributes(new String[]{"description"});
fs.update(folderRef, folderVO, true, true);

Invoking setDirtyAttributes is required for Web Services clients because of the way Axis deserializes XML objects from XML. If setDirtyAttributes is not invoked, Axis calls setters on all attributes of the VO, including read-only attributes, resulting in a ReadOnlyException.

Compatibility with SA Web Services API 2.2

The SA Web Services API 2.2 is not compatible with the SA API described in this guide. The method signatures, services, WSDLs, and port bindings are not the same. If you are creating new Web Services clients, be sure to use the SA API, not the SA Web Services API 2.2.