There can be times when creating component dependencies in a deployable unit where a specific dependency target may not be known. For example, the particular version of a dependent library may be variable. At other times, some already installed component may need to be replaced with another, possibly a new version with a bug fix, and reinstalling all dependent components with updated deployment descriptors is undesirable.

Bindings can help with this problem, to some degree, however bindings can introduce other issues. Bindings always operate on virtual copies of the original components, and keeping track of copied components can be difficult if many binding operations are made.

Rhino provides a solution to these problems with support for linked and shadowed components.

Linked components

A linked component is a virtual component that provides an alias for some other component. Incoming references to the linked component are redirected to the link target. A linked component’s component type, for example SBB, profile specification, library, and so on, is the same as the component that it is linked to; and, like all other components, has a unique identity represented by the (name, vendor, version) tuple.

A linked component identifier can be used anywhere where a regular component identifier is required.

Shadowed components

A shadowed component is an existing component that has been "shadowed" or replaced by a link to another component of the same type. Incoming references to the shadowed component are redirected to the link target rather than using the original component.

Conceptually, linked and shadowed component perform the same function: to redirect an incoming reference to another component. The difference is that a linked component is a new virtual component with a unique identity, whereas a shadow replaces a component that is already installed in the SLEE.

Note
Components supporting links and shadows

The following types of components currently support links and shadows:

  • services

  • SBBs

  • SBB parts

  • profile specifications

  • resource adaptor types

  • resource adaptors

  • event types

  • libraries.

Managing linked components

Below are overviews of the procedures to create, remove, and view the metadata for linked components.

Creating a linked component

You create linked components using the createLinkedComponent management operation. For example, using rhino-console:

[Rhino@localhost:2199 (#0)] createlinkedcomponent sbb name=MySBB,vendor=OpenCloud,version=1.0 MySBBLink OpenCloud 1.0
Component SbbID[name=MySBBLink,vendor=OpenCloud,version=1.0] linked to SbbID[name=MySBB,vendor=OpenCloud,version=1.0]

The first two arguments identify the component type and identifier of the link target. The target component must already exist in the SLEE. The last three arguments define the name, vendor, and version strings for the new linked component identifier.

Removing a linked component

You remove a linked component using the removeLinkedComponent management operation. For example, using rhino-console:

[Rhino@localhost:2199 (#0)] removelinkedcomponent sbb name=MySBBLink,vendor=OpenCloud,version=1.0
Linked component SbbID[name=MySBBLink,vendor=OpenCloud,version=1.0] removed

A linked component cannot be removed if:

  • another component with an install level of VERIFIED or DEPLOYED references it;

  • another linked component specifies this linked component as its target; or

  • another component is shadowed by this linked component.

Viewing linked component metadata

The getDescriptor management operation returns a SLEE ComponentDescriptor object for any component that exists in the SLEE. A ComponentDescriptor object for a linked component has the following properties:

  • its deployable unit is the same as the deployable unit of the link target

  • its source component jar is the same as the source component jar of the link target

  • it contains a vendor-specific data object of type LinkedComponentDescriptorExtensions.

Linked component descriptor extensions

The LinkedComponentDescriptorExtensions class defines Rhino-specific component metadata extensions for linked components. Here’s what it looks like:

package com.opencloud.rhino.management.deployment;

import java.io.Serializable;
import java.util.Date;
import javax.slee.ComponentID;

public class LinkedComponentDescriptorExtensions implements Serializable {
    public LinkedComponentDescriptorExtensions(...) { ... }

    public ComponentID getLinkTarget() { ... }

    public Date getLinkDate() { ... }

    public InstallLevel getInstallLevel() { ... }

    public ComponentID[] getIncomingLinks() { ... }

    public ComponentID[] getShadowing() { ... }

    ...
}

  • The getLinkTarget method returns the component identifier of the link target.

  • The getLinkDate method returns a Date object that specifies the date and time the linked component was created.

  • The getInstallLevel method returns the current install level of the linked component. The install level of a linked component is immaterial, and changing it has no effect on the linked component itself; however, since an install level is a property of all components installed in Rhino, a linked component must have one by definition.

  • The getIncomingLinks method returns the component identifiers of any other linked components that have this linked component as a target.

  • The getShadowing method returns the component identifiers of any other component that has been shadowed by this linked component.

Managing component shadows

Shadowing or unshadowing a component effectively changes the definition of the component; therefore a component can only undergo these transitions if it has an install level of INSTALLED. This ensures that any components that depend on the affected component also have an install level of INSTALLED, and thus will need (re)verifying against the updated component before further use. Rhino will allow a component with an install level of VERIFIED to be shadowed or unshadowed, but will automatically transition the component (and any upstream dependencies) to the INSTALLED install level first. A component with an install level of DEPLOYED must be manually undeployed before a shadow can be created or removed.

Below are overviews of the procedures to shadow, unshadow, and view the shadow metadata for a component.

Shadowing a component

You shadow one component with another using the shadowComponent management operation. For example, using rhino-console:

[Rhino@localhost:2199 (#0)] shadowcomponent sbb name=MySBB,vendor=OpenCloud,version=1.0 name=MySBB,vendor=OpenCloud,version=1.0.2
Component SbbID[name=MySBB,vendor=OpenCloud,version=1.0] shadowed by SbbID[name=MySBB,vendor=OpenCloud,version=1.0.2]

The first two arguments identify the component type and identifier of the component to be shadowed. The last argument identifies the component that this component will be shadowed by. Both the shadowed and shadowing components must already exist in the SLEE.

Warning
Link cycles won’t work

Using shadows, you might try to create a link cycle. For example, if component A is a link to component B, component B is a link to component C, and component C is shadowed by component A, then a link cycle would exist which cannot be resolved to any concrete component. Rhino forbids such cycles to be created. An attempt to shadow a component with another component that would result in a link cycle will fail with an appropriate error.

Unshadowing a component

You unshadow a component using the unshadowComponent management operation. For example, using rhino-console:

[Rhino@localhost:2199 (#0)] unshadow sbb name=MySBB,vendor=OpenCloud,version=1.0
Shadow removed from component SbbID[name=MySBB,vendor=OpenCloud,version=1.0]

Viewing shadowed component metadata

The getDescriptor management operation returns a SLEE ComponentDescriptor object for any component that exists in the SLEE. The component descriptor for a shadowed component continues to describe the original unshadowed component, but contains a vendor-specific data object of type com.opencloud.rhino.management.deployment.ComponentDescriptorExtensions that includes the following information relevant to shadowing:

  • The getShadowedBy method returns the component identifier of the component that shadows this component. This target component will be used in place of the described component.

  • The getShadowDate method returns a Date object that specifies the date and time the shadow was established.

  • The getShadowing method returns the component identifiers of any other component that has in turn been shadowed by this shadowed component.

Linked and shadowed component resolution

In most cases where a component identifier is specified, Rhino will follow a chain of links and shadows to resolve the component identifier to a concrete target component. Typical cases where this occurs are as follows:

  • wherever a component references another component in its deployment descriptor or in a binding descriptor

  • if a service component is activated or deactivated

  • when a profile table is created from a profile specification
    (though Rhino will report that the profile table was created from the specified component rather than the resolved target)

  • when a resource adaptor entity is created from a resource adaptor
    (though again Rhino will report that the resource adaptor entity was created from the specified component rather than the resolved target)

  • when interrogating or updating a component’s security policy.

Specific cases where a management operation applies directly to a linked or shadowed component rather than its resolved target are as follows:

  • when requesting a component’s metadata descriptor

  • when copying a shadowed component
    (The shadowed component itself is copied, rather than the shadowing component. Linked components are still resolved though when determining the actual component to copy; so an attempt to copy a linked component will result in a copy of the resolved target component being copied.)

Additional notes

  • Creating a link to a service component automatically adds a clone of the resolved target service’s statistics with the linked component identifier to the stats manager. For example, if service component A is linked to service component B, then the stats for B can be accessed from the stats manager using either component identifier A or B. The same result will be obtained in each case. Listing the available stats parameter sets will include both A and B.

  • The activation state reported for a linked or shadowed service component is the state of the service component that the link or shadow resolves to. Activating or deactivating the linked or shadowed component has the same effect as activating or deactivating the resolved component.

  • If a resource adaptor entity generates events that may be consumed by a given service component, and a link to that service component is created, then the resource adaptor entity will also be notified about a change to the lifecycle state for the linked component when the state of the target service component changes.

  • A resource adaptor entity may fire an event targeted at a linked service component, and Rhino will deliver the event to the resolved target service component. If an SBB in the service invokes a resource adaptor interface API method while handling that event, then the value returned by the ResourceAdaptorContext.getInvokingService() method will equal the target service component identifier specified by the resource adaptor entity when the event was fired; that is, it will be the linked component identifier. However if an SBB in the service invokes a resource adaptor interface API method while handling an event that had no specific service target, then the value returned by the same getInvokingService() method will be the service component identifier of the resolved service that is actually processing the event.

Previous page Next page
Rhino Version 2.7.0