3 SPI Capabilities and Versions

This chapter describes how an SPI implementation exposes the capabilities it supports to the VCR. This chapter includes the following topics:

• Section 3.1, "About SPI Capabilities"

• Section 3.2, "VCR Detection of the SPI Implementation Capabilities"

• Section 3.3, "SPI Interface Versions"

3.1 About SPI Capabilities

The SPI implementation exposes the capabilities it supports to the VCR. For example, an SPI implementation may report which methods it supports, and whether it supports Node creation. This allows the VCR and VCR client code to customize behavior based on the capabilities of the underlying SPI implementation. There are three types of capabilities:

• Method capabilities

• Feature capabilities

• Repository defined capabilities

Method capabilities indicate which methods on an interface. These are exposed via:

• Repository – Repository.getCapabilitySupport()

• Ticket – Ticket.getCapabilitySupport()

Feature capabilities are exposed with Repository.getCapabilitySupport(). CM features may span multiple methods. For example, NodeFeatureCapability.NodeUpdate affects several methods and indicates the general ability to update a node.

Repository-defined capabilities are optional SPI implementation-specific functions. These capabilities are exposed with Repository.getRepositoryDefinedCapabilities() and report various (usually dynamic) abilities of the underlying repository to the VCR client code for a specific SPI implementation. For example, you could use an SPI implementation to report to client code that the SPI implementation is performing case-insensitive sorting. A basic SPI implementation likely would not use this feature.

3.2 VCR Detection of the SPI Implementation Capabilities

For method and feature capabilities, the VCR passes the set of capabilities it is aware of to the SPI. The SPI implementation must then report its capability support (supported or not supported) for each capability passed. The SPI implementation must not report any additional capabilities beyond those it was passed. If additional capabilities exist, the implementation should use repository-defined capabilities for those capabilities.

For repository-defined capabilities, the VCR simply asks the repository for its repository defined capabilities and associated support levels.

During the connection process, the VCR calls the methods:

• Repository.getCapabilitySupport(...) – Defines how the SPI implementation reports its feature capability support. If the Repository implements any optional repository operation interfaces, such as RepositoryConfigOpsV1, it must report a MethodCapability for each method in these interfaces.

• Ticket.getCapabilitySupport(...) – If the Ticket implements any optional ticket operation interfaces, such as NodeOpsV1, it must report a MethodCapability for each method in these interfaces.

• Repository.getRepositoryDefinedCapabilities() – Defines how the SPI implementation can report any repository-defined capabilities.

3.3 SPI Interface Versions

The SPI model included in WebLogic Portal allows the VCR and SPI implementation to have different versions of the SPI interfaces. For example, the VCR may use NodeOpsV3 while the SPI implementation may be written to NodeOpsV2. This flexibility allows the SPI to expand over time without breaking any existing SPI implementations and allow additional interfaces to be introduced that expose additional functionality. The SPI version numbers are unrelated to the WebLogic Portal product version; they are incremented anytime an interface change is made.

Note:

Once an SPI interface version is released with WebLogic Portal, it will not change because changing it may break any SPI implementations that implement its version.

Versioned interfaces exist for optional repository operation interfaces, such as RepositoryConfigOpsV1 and optional ticket operation interfaces, such as NodeOpsV1. When you create an SPI implementation, you write the implementation for specific versions of the SPI interfaces.

For example, suppose that WebLogic Portal v11 includes NodeOpsV1, ObjectClassOpsV1, and ObjectClassOpsV2 (among others) and you write an SPI implementation against WebLogic Portal v11 to implement the latest versions: NodeOpsV1 and ObjectClassOpsV2. After a period of time, when you use WebLogic Portal v12, which includes NodeOpsV1, NodeOpsV2, ObjectClassOpsV1, ObjectClassOpsV2, and ObjectClassOpsV3, the SPI implementation, built to earlier versions, works properly.

Tip:

You should use the latest available versions of the interfaces for your SPI implementations. Over time, SPI interface versions may be deprecated and eventually removed, so it's best to start with the latest available.

You do not need to implement all methods in the interfaces. For example, you could implement only a single method in NodeOpsV1.

Some SPI Implementation methods report the interface version they implement. For example, Repository.getAllInterfaces() and Ticket.getAllInterfaces() return a Map<String, ISPIMarker>, which has a key with the interface version: SPIRepositoryInterfaces.REPOSITORY_CONFIG_OPS_V1 or SPITicketInterfaces.NODE_OPS_V1.

Note:

You should not bundle the versioned SPI interface classes in the SPI JARs with your SPI implementations; they are included with WebLogic Portal.