com.opencloud.rhino.management.deployment

Interface DeploymentMBean

All Superinterfaces:

DeploymentMBean

public interface DeploymentMBean
extends DeploymentMBean

The DeploymentMBean interface defines deployment-related management operations. Using the DeploymentMBean a management client may install and remove deployment unit jar files in to and out from the SLEE, obtain lists and/or descriptors of the various types of components installed in the SLEE, and generate dependency graphs of the installed components.

Links and Shadows

Unless otherwise stated, all methods that take one or more ComponentID as an argument will follow the links contained by linked and shadowed components recursively when determining the actual component(s) to apply the operation to. For example, if a linked component is given as an argument to the deploy(ComponentID) method, the target of the linked component will be that which is deployed.

Field Summary

Fields inherited from interface javax.slee.management.DeploymentMBean

OBJECT_NAME

Method Summary

Modifier and Type	Method and Description
ComponentAuditResult	auditComponent(ComponentID id) Audit a component and its dependencies for potential classloader problems.
void	copyComponent(ComponentID source, ComponentID target, InstallLevel installLevel) Create a new component as a copy of an existing component.
void	createLinkedComponent(ComponentID source, ComponentID target) Create a linked component.
ComponentID[]	deploy(ComponentID id) Deploy a component.
ComponentID[]	deploy(DeployableUnitID id) Deploy a deployable unit.
ComponentID[]	getAllCopies(ComponentID id) Get the set of components that are copies of the specified component, either directly or indirectly.
BindingDescriptorID[]	getBindingDescriptors() Get the set of binding descriptors installed in the SLEE.
Map<ComponentID,InstallLevel>	getComponentInstallLevels(DeployableUnitID id) Returns the InstallLevel of the components in the specified deployable unit.
DeployableType[]	getDeployableTypes() Get the recognized deployable types that may be installed into the SLEE.
byte[]	getDeployableUnit(DeployableUnitID id) Get the contents of the specified deployable unit jar file.
DeployableUnitID	getDeployableUnit(String url)
ComponentDescriptor	getDescriptor(ComponentID id) Get the component descriptor for a component identifier.
DeployableUnitDescriptor	getDescriptor(DeployableUnitID id) Get the deployable unit descriptor for a deployable unit.
ComponentDescriptor[]	getDescriptors(ComponentID[] ids)
DeployableUnitDescriptor[]	getDescriptors(DeployableUnitID[] ids)
Map<String,String>	getEnvEntries(ComponentID id, boolean original) Returns a Map containing String representations of the env entries for the specified component.
ComponentID[]	getReferringComponents(ComponentID id) Get the set of components that use or make reference to a specified component.
String[]	getRhinoPolicy(int[] nodes) Returns the currently active JVM security policies for the specified nodes.
String	getSasBundle() Creates a SAS Bundle by inspecting all deployed deployable units.
SbbPartID[]	getSbbParts() Get the set of SBB parts installed in the SLEE.
SbbID[]	getSbbs(ServiceID service)
String	getSecurityPolicy(ComponentID id, String subId, boolean original) Returns the current or original security policy associated with the specified component.
DeployableUnitID	install(DeployableType deployableType, String url, byte[] content, InstallLevel installLevel) Install a deployable unit file into the SLEE.
DeployableUnitID	install(DeployableType deployableType, String url, byte[] content, InstallLevel installLevel, boolean assignBundlePrefixes) Install a deployable unit file into the SLEE.
DeployableUnitID	install(DeployableType deployableType, String url, InstallLevel installLevel) Install a deployable unit file into the SLEE.
DeployableUnitID	install(String url, byte[] content) Install a deployable unit jar file into the SLEE.
boolean	isInstalled(ComponentID id)
boolean	isInstalled(DeployableUnitID id)
void	removeCopiedComponent(ComponentID id) Remove a copied component.
void	removeCopiedComponents(ComponentID[] ids) Remove a set of copied components.
ComponentID[]	removeCopiedComponents(DeployableUnitID id) Remove all copied components made from components in the specified deployable unit.
void	removeLinkedComponent(ComponentID id) Remove an existing linked component.
void	setEnvEntries(ComponentID id, Map<String,String> entries) Sets the env entries for the specified component.
void	setSecurityPolicy(ComponentID id, String subId, String policyText) Set the security policy for the specified component.
void	shadowComponent(ComponentID source, ComponentID target) Shadow an existing component with another component.
ComponentID[]	undeploy(ComponentID id) Undeploy a component.
void	unshadowComponent(ComponentID id) Remove the shadow from a shadowed component.
ComponentID[]	unverify(ComponentID id) Unverify a component.
ComponentID[]	verify(ComponentID id) Verify a component.
ComponentID[]	verify(DeployableUnitID id) Verify a deployable unit.

Methods inherited from interface javax.slee.management.DeploymentMBean

getDeployableUnits, getEventTypes, getLibraries, getProfileSpecifications, getResourceAdaptors, getResourceAdaptorTypes, getSbbs, getServices, install, uninstall

Method Detail

getDeployableTypes

DeployableType[] getDeployableTypes()

Get the recognized deployable types that may be installed into the SLEE.

Returns:

an array of deployable types.

Since:

Rhino 2.4.0

install

DeployableUnitID install(String url,
                         byte[] content)
                  throws NullPointerException,
                         MalformedURLException,
                         AlreadyDeployedException,
                         DeploymentException,
                         ManagementException

Install a deployable unit jar file into the SLEE. Rather than retrieve the deployable unit from the specified URL, the actual file contents of the deployable unit are passed in as a parameter to this method, and the SLEE installs the deployable unit as if it was being installed from the URL.

Parameters:

url - the URL to pretend to install the deployable unit as.

content - the deployable unit jar file contents to install.

Returns:

a DeployableUnitID that identifies the installed jar file.

Throws:

NullPointerException - if either argument is null.

MalformedURLException - if url is not a properly formatted URL.

AlreadyDeployedException - if the URL has already been installed, or the jar file contains a component with the same type and identity as a component already installed.

DeploymentException - if the jar file could not be successfully installed due to a problem directly related to it or any of it contained components.

ManagementException - if the jar file could not be successfully installed due to a system-level failure.

install

DeployableUnitID install(DeployableType deployableType,
                         String url,
                         InstallLevel installLevel)
                  throws NullPointerException,
                         MalformedURLException,
                         AlreadyDeployedException,
                         DeploymentException,
                         ManagementException

Install a deployable unit file into the SLEE. The requirements for a successful install depend on the type of deployable unit being installed.

Parameters:

deployableType - the type of deployable unit to install.

url - the URL of the deployable unit file.

installLevel - the degree to which the deployable unit should be installed.

Returns:

a DeployableUnitID that identifies the installed file.

Throws:

NullPointerException - if any argument is null.

MalformedURLException - if url is not a properly formatted URL.

AlreadyDeployedException - if the URL has already been installed, or the deployable unit contains a component with the same type and identity as a component already installed.

DeploymentException - if the deployable unit could not be successfully installed due to a problem directly related to it or any of it contained components.

ManagementException - if the deployable unit could not be successfully installed due to a system-level failure.

Since:

Rhino 2.4.0

install

DeployableUnitID install(DeployableType deployableType,
                         String url,
                         byte[] content,
                         InstallLevel installLevel)
                  throws NullPointerException,
                         MalformedURLException,
                         AlreadyDeployedException,
                         DeploymentException,
                         ManagementException

Install a deployable unit file into the SLEE. Rather than retrieve the deployable unit from the specified URL, the actual file contents of the deployable unit are passed in as a parameter to this method, and the SLEE installs the deployable unit as if it was being installed from the URL.

Parameters:

deployableType - the type of deployable unit to install.

url - the URL to pretend to install the deployable unit as.

content - the deployable unit file contents to install.

installLevel - the degree to which the deployable unit should be installed.

Returns:

a DeployableUnitID that identifies the installed file.

Throws:

NullPointerException - if any argument is null.

MalformedURLException - if url is not a properly formatted URL.

AlreadyDeployedException - if the URL has already been installed, or the deployable unit contains a component with the same type and identity as a component already installed.

DeploymentException - if the deployable unit could not be successfully installed due to a problem directly related to it or any of it contained components.

ManagementException - if the deployable unit could not be successfully installed due to a system-level failure.

Since:

Rhino 2.4.0

install

DeployableUnitID install(DeployableType deployableType,
                         String url,
                         byte[] content,
                         InstallLevel installLevel,
                         boolean assignBundlePrefixes)
                  throws NullPointerException,
                         MalformedURLException,
                         AlreadyDeployedException,
                         DeploymentException,
                         ManagementException

Install a deployable unit file into the SLEE. Rather than retrieve the deployable unit from the specified URL, the actual file contents of the deployable unit are passed in as a parameter to this method, and the SLEE installs the deployable unit as if it was being installed from the URL.

Parameters:

deployableType - the type of deployable unit to install.

url - the URL to pretend to install the deployable unit as.

content - the deployable unit file contents to install.

installLevel - the degree to which the deployable unit should be installed.

assignBundlePrefixes - if true, assign bundle prefixes to any SAS mini-bundles in the DU (defaults to true)

Returns:

a DeployableUnitID that identifies the installed file.

Throws:

NullPointerException - if any argument is null.

MalformedURLException - if url is not a properly formatted URL.

AlreadyDeployedException - if the URL has already been installed, or the deployable unit contains a component with the same type and identity as a component already installed.

DeploymentException - if the deployable unit could not be successfully installed due to a problem directly related to it or any of it contained components.

ManagementException - if the deployable unit could not be successfully installed due to a system-level failure.

Since:

Rhino 2.6.0

verify

ComponentID[] verify(DeployableUnitID id)
              throws NullPointerException,
                     UnrecognizedDeployableUnitException,
                     DeploymentException,
                     ManagementException

Verify a deployable unit. This is a convenience operation to verify all the components in the deployable unit. If any dependant components have not yet been verified, they will also be verified as a part of this operation.

This method has no further effect if all components in the deployable unit have already been verified.

Parameters:

id - the identifier of the deployable unit to verify.

Returns:

the set of components whose install level changed as a result of this operation.

Throws:

NullPointerException - if id is null.

UnrecognizedDeployableUnitException - if id is not a recognisable DeployableUnitID object for the SLEE or it does not correspond with a deployable unit installed in the SLEE.

DeploymentException - if the verification check fails due to a problem directly related to it, any of its contained components, or any dependent components that also need to be verified as a consequence.

ManagementException - if the deployable unit could not be successfully verified due to a system-level failure.

Since:

Rhino 2.4.0

See Also:

@see #deploy(DeployableUnitID)

deploy

ComponentID[] deploy(DeployableUnitID id)
              throws NullPointerException,
                     UnrecognizedDeployableUnitException,
                     DeploymentException,
                     ManagementException

Deploy a deployable unit. This is a convenience operation to deploy all the components in the deployable unit. If any dependant components have not yet been deployed, they will also be deployed as a part of this operation.

Any affected component that has not yet been verified will be verified before the deployment occurs.

This method has no further effect if all components in the deployable unit have already been deployed.

Parameters:

id - the identifier of the deployable unit to deploy.

Returns:

the set of components whose install level changed as a result of this operation.

Throws:

NullPointerException - if id is null.

UnrecognizedDeployableUnitException - if id is not a recognisable DeployableUnitID object for the SLEE or it does not correspond with a deployable unit installed in the SLEE.

DeploymentException - if the deployment fails due to a problem directly related to it, any of its contained components, or any dependent component that also need to be deployed as a consequence.

ManagementException - if the deployable unit could not be successfully verified due to a system-level failure.

Since:

Rhino 2.4.0

See Also:

@see #deploy(ComponentID)

getComponentInstallLevels

Map<ComponentID,InstallLevel> getComponentInstallLevels(DeployableUnitID id)
                                                 throws NullPointerException,
                                                        UnrecognizedDeployableUnitException,
                                                        DeploymentException,
                                                        ManagementException

Returns the InstallLevel of the components in the specified deployable unit.

This will include all copied components but not linked components. Shadowed components will be ignored.

Parameters:

id - the identifier of the deployable unit.

Returns:

the map of InstallLevels of each ComponentID.

Throws:

NullPointerException - if id is null.

ManagementException - if the InstallLevel deployable components could not be retrieved due to a system-level failure.

UnrecognizedDeployableUnitException

DeploymentException

Since:

Rhino 2.5.0

verify

ComponentID[] verify(ComponentID id)
              throws NullPointerException,
                     UnrecognizedComponentException,
                     InvalidStateException,
                     DeploymentException,
                     ManagementException

Verify a component. The verification process checks that all referenced components exist and that any declared component classes or interfaces comply with the relevant requirements.

If any dependant components have not yet been verified, they will also be verified as a part of this operation.

Parameters:

id - the component identifier of the component to verify.

Returns:

the set of components, other than the component identified by id, whose install level changed as a result of this operation.

Throws:

NullPointerException - if id if null.

UnrecognizedComponentException - if id is not a recognisable ComponentID object for the SLEE or it does not correspond with a component installed in the SLEE.

InvalidStateException - if the component has already been verified.

DeploymentException - if the verification check fails due to a problem directly related to the component or any dependent components that also need to be verified as a consequence.

ManagementException - if the component could not be successfully verified due to a system-level failure.

Since:

Rhino 2.4.0

See Also:

@see #deploy(ComponentID)

unverify

ComponentID[] unverify(ComponentID id)
                throws NullPointerException,
                       UnrecognizedComponentException,
                       DependencyException,
                       InvalidStateException,
                       ManagementException

Unverify a component. The verified status of the component is removed, and any links it had to other installed components are broken.

If any components that depend on the component to be unverified are themselves verified, they will also be unverified as a part of this operation. Any deployed components will be undeployed before being unverified.

Parameters:

id - the component identifier of the component to verify.

Returns:

the set of components, other than the component identified by id, whose install level changed as a result of this operation.

Throws:

NullPointerException - if id if null.

UnrecognizedComponentException - if id is not a recognisable ComponentID object for the SLEE or it does not correspond with a component installed in the SLEE.

DependencyException - if any other entity present in the SLEE, such as a profile table or resource adaptor entity, is dependent on any of the components being unverified.

InvalidStateException - if the component is not currently verified, or if any of the components being unverified are not in a state where they may be unverified. For example, a deployed service cannot be undeployed and unverified while it is in the ACTIVE state.

ManagementException - if the component could not be successfully unverified due to a system-level failure.

Since:

Rhino 2.4.0

See Also:

verify(ComponentID)

deploy

ComponentID[] deploy(ComponentID id)
              throws NullPointerException,
                     UnrecognizedComponentException,
                     InvalidStateException,
                     DeploymentException,
                     ManagementException

Deploy a component. The deployment process generates any necessary implementation code then publishes the component to the SLEE’s runtime subsystem, readying the component for immediate use.

If any dependant components have not yet been deployed, they will also be deployed as a part of this operation. Any affected component that has not yet been verified will be verified before the deployment occurs.

Parameters:

id - the component identifier of the component to deploy.

Returns:

the set of components, other than the component identified by id, whose install level changed as a result of this operation.

Throws:

NullPointerException - if id if null.

UnrecognizedComponentException - if id is not a recognisable ComponentID object for the SLEE or it does not correspond with a component installed in the SLEE.

InvalidStateException - if the component has already been deployed. The current install level of the component can be obtained from the vendor data included in the component’s descriptor.

DeploymentException - if the deployment fails due to a problem directly related to the component or any dependent components that also need to be verified as a consequence.

ManagementException - if the component could not be successfully deployed due to a system-level failure.

Since:

Rhino 2.4.0

See Also:

@see #verify(ComponentID)

undeploy

ComponentID[] undeploy(ComponentID id)
                throws NullPointerException,
                       UnrecognizedComponentException,
                       DependencyException,
                       InvalidStateException,
                       ManagementException

Undeploy a component. The component is removed from the SLEE’s runtime subsystem and any implementation code generated for it is deleted.

Undeployment is necessary, for example, if metadata bindings need to be added or removed from a Service. These bindings cannot be changed while the Service is deployed.

If any components that depend on the component to be undeployed are themselves deployed, they will also be undeployed as a part of this operation.

Parameters:

id - the component identifier of the component to undeploy.

Returns:

the set of components, other than the component identified by id, whose install level changed as a result of this operation.

Throws:

NullPointerException - if id if null.

UnrecognizedComponentException - if id is not a recognisable ComponentID object for the SLEE or it does not correspond with a component installed in the SLEE.

DependencyException - if any other entity present in the SLEE, such as a profile table or resource adaptor entity, is dependent on any of the components being undeployed.

InvalidStateException - if the component is not currently deployed, or if any of the components being undeployed are not in a state where they may be undeployed. For example, a deployed service cannot be undeployed while it is in the ACTIVE state.

ManagementException - if the component could not be successfully undeployed due to a system-level failure.

Since:

Rhino 2.4.0

See Also:

deploy(ComponentID)

copyComponent

void copyComponent(ComponentID source,
                   ComponentID target,
                   InstallLevel installLevel)
            throws NullPointerException,
                   UnrecognizedComponentException,
                   InvalidArgumentException,
                   AlreadyDeployedException,
                   DeploymentException,
                   ManagementException

Create a new component as a copy of an existing component. The new component initially inherits all the component references and configuration state of the source component.

Links and Shadows

If the source component is a linked component, this method will follow the link when determining the component to copy.

If the source component is a shadowed component, or a link to a shadowed component, the shadowing link will not be followed and the shadowed component itself will be copied. This allows shadowed components to be copied without requiring them be unshadowed first. If a copy of the shadowing component is required, then the component identifier of the shadowing component should be specified as the source argument.

Copying Services

If a service component is copied, the copied service will be initialised to the INACTIVE state, irrespective of the state of the original service.

Copying a service is typically made with the intent of modifying its metadata bindings. In this case, it is most efficient to copy using an install level of InstallLevel.INSTALLED, and then verify and deploy the copied service after the binding changes have been made.

Parameters:

source - the component identifier of the component to copy.

target - the component identifier of the component to create.

installLevel - the degree to which the copied component should be installed.

Throws:

NullPointerException - if any argument is null.

UnrecognizedComponentException - if source is not a recognisable ComponentID object for the SLEE or it does not correspond with a component installed in the SLEE.

InvalidArgumentException - if source and target represent different types of components.

AlreadyDeployedException - if a component with target identity is already installed in the SLEE.

DeploymentException - if the component could not be copied due to a problem directly related to it.

ManagementException - if the component could not be copied due to a system-level failure.

Since:

Rhino 2.4.0

See Also:

@see #deploy(ComponentID)

getAllCopies

ComponentID[] getAllCopies(ComponentID id)
                    throws NullPointerException,
                           UnrecognizedComponentException,
                           ManagementException

Get the set of components that are copies of the specified component, either directly or indirectly.

Consider an example where:

• Component c1 is an original component, installed using a standard deployable unit.

• Component c2 is a direct copy of c1.

• Component c3 is a direct copy of c2.

then:

• getAllCopies(c1) will return [c2, c3]

• getAllCopies(c2) will return [c3]

Links and Shadows

If id is a linked component, this method will follow the link when determining the component to return the copies of.

If id is a shadowed component, or a link to a shadowed component, the shadowing link will not be followed and the identifiers of the components copied from the shadowed component itself will be returned. This allows shadowed components to be interrogated without requiring them be unshadowed first. If the copies of the shadowing component are required, then the component identifier of the shadowing component should be specified as the id argument.

Parameters:

id - the component identifier of the component to get copies for.

Returns:

the copied components.

Throws:

NullPointerException - if id is null.

UnrecognizedComponentException - if id is not a recognisable ComponentID object for the SLEE or it does not correspond with a component installed in the SLEE.

ManagementException - if the set of copied components could not be retrieved due to a system-level failure.

Since:

Rhino 2.4.0

removeCopiedComponents

ComponentID[] removeCopiedComponents(DeployableUnitID id)
                              throws NullPointerException,
                                     UnrecognizedDeployableUnitException,
                                     DependencyException,
                                     InvalidStateException,
                                     ManagementException

Remove all copied components made from components in the specified deployable unit.

Parameters:

id - the identifier of the deployable unit.

Returns:

the copied components that have been removed. The returned array will be zero-length if no copies have been made of the deployable unit’s components.

Throws:

NullPointerException - if id is null.

UnrecognizedDeployableUnitException - if id is not a recognisable DeployableUnitID object for the SLEE or it does not correspond with a deployable unit installed in the SLEE.

DependencyException - if any other component installed in the SLEE is dependent on any of the components being removed.

InvalidStateException - if any of the components being removed can not be removed due to being in an invalid state. For example, a service cannot be removed while it is in the ACTIVE state, and a component cannot be removed while it is shadowed.

ManagementException - if the components could not be removed due to system-level failure.

Since:

Rhino 2.4.0

removeCopiedComponent

void removeCopiedComponent(ComponentID id)
                    throws NullPointerException,
                           UnrecognizedComponentException,
                           InvalidArgumentException,
                           DependencyException,
                           InvalidStateException,
                           ManagementException

Remove a copied component.

Parameters:

id - the identifier of the copied component to remove. Links and shadows are not followed by this method, ie. id must itself be a copied component.

Throws:

NullPointerException - if id is null.

UnrecognizedComponentException - if id is not a recognisable ComponentID object for the SLEE or it does not correspond with a component installed in the SLEE.

InvalidArgumentException - if id does not represent the identity of a component that has been copied from another.

DependencyException - if any other component installed in the SLEE is dependent on the component being removed.

InvalidStateException - if the component cannot be removed due to being in an invalid state. For example, a service cannot be removed while it is in the ACTIVE state, and a component cannot be removed while it is shadowed.

ManagementException - if the component could not be removed due to a system-level failure.

Since:

Rhino 2.4.0

removeCopiedComponents

void removeCopiedComponents(ComponentID[] ids)
                     throws NullPointerException,
                            UnrecognizedComponentException,
                            InvalidArgumentException,
                            DependencyException,
                            InvalidStateException,
                            ManagementException

Remove a set of copied components.

Parameters:

ids - a set of component identifiers of the components to be removed.

Throws:

NullPointerException - if ids is null.

UnrecognizedServiceException - if any member of ids is not a recognizable ServiceID for the SLEE or does not correspond with a Service installed in the SLEE.

UnrecognizedComponentException - if any member of ids is not a recognisable ComponentID object for the SLEE or does not correspond with a component installed in the SLEE.

InvalidArgumentException - if ids is zero-length, contains null or duplicate elements, or contains an element that does not represent the identity of a component that has been copied from another.

DependencyException - if any other component installed in the SLEE is dependent on any of the components being removed.

InvalidStateException - if any of the components being removed can not be removed due to being in an invalid state. For example, a service cannot be removed while it is in the ACTIVE state.

ManagementException - if the components could not be removed due to a system-level failure.

Since:

Rhino 2.4.0

createLinkedComponent

void createLinkedComponent(ComponentID source,
                           ComponentID target)
                    throws NullPointerException,
                           AlreadyDeployedException,
                           UnrecognizedComponentException,
                           InvalidArgumentException,
                           ManagementException

Create a linked component. A linked component is a virtual component that provides an alias for some other component. A linked component identifier can be used anywhere where a regular component identifier is required.

The identifiers for a linked component and its target component must be of the same type. For example, if the target component is a service then the linked component identifier must be a service identifier. The target component of a link may be any component, for example it could itself be another linked component. Links are not followed by this method, ie. the link target will be exactly that as specified by the target argument.

The following types of components may be linked:

• services

• SBBs

• SBB parts

• profile specifications

• resource adaptor types

• resource adaptors

• event types

• libraries

Parameters:

source - the identifier of the linked component to create.

target - the identifier of the component that is the target of the link.

Throws:

NullPointerException - if either argument is null.

AlreadyDeployedException - if target identifies a component that is already installed in the SLEE.

UnrecognizedComponentException - if target is not a recognisable ComponentID object for the SLEE or it does not correspond with a component installed in the SLEE.

InvalidArgumentException - if source and target are not the same Java type, or if the component type of target does not support linking.

ManagementException - if the linked component could not be created due to a system-level failure.

Since:

Rhino 2.4.0

removeLinkedComponent

void removeLinkedComponent(ComponentID id)
                    throws NullPointerException,
                           UnrecognizedComponentException,
                           InvalidArgumentException,
                           DependencyException,
                           ManagementException

Remove an existing linked component.

Parameters:

id - the identifier of the linked component to remove.

Throws:

NullPointerException - if id is null.

UnrecognizedComponentException - if id is not a recognisable ComponentID object for the SLEE or it does not correspond with a component installed in the SLEE.

InvalidArgumentException - if id does not correspond with a linked component.

DependencyException - if any other component installed in the SLEE is dependent on the linked component.

ManagementException - if the linked component could not be removed due to a system-level failure.

Since:

Rhino 2.4.0

shadowComponent

void shadowComponent(ComponentID source,
                     ComponentID target)
              throws NullPointerException,
                     UnrecognizedComponentException,
                     InvalidArgumentException,
                     InvalidStateException,
                     ManagementException

Shadow an existing component with another component. A shadowed component is effectively replaced by the component that shadows it, such that any references to the shadowed component are redirected to the shadowing component.

The identifiers for the shadowed and shadowing components must be of the same type. For example, a service component can only be shadowed by another service component. The shadowing component may be any component, for example it may be a linked component or another component that is itself shadowed. Links are not followed by this method, ie. the shadow target will be exactly that as specified by the target argument.

The following types of components may be shadowed:

• services

• SBBs

• SBB parts

• profile specifications

• resource adaptor types

• resource adaptors

• event types

• libraries

Only original and copied components may be shadowed. Linked components cannot be shadowed. An already shadowed component cannot be shadowed again, instead the existing shadow must be removed first before the new shadow applied.

Only components with an install level of InstallLevel.INSTALLED may be shadowed. If the install level of source is VERIFIED, then this method will automatically unverify the component (and any relevant dependent components) before applying the shadow. A component with an install level of InstallLevel.DEPLOYED must be manually undeployed first before it can be shadowed.

Parameters:

source - the identifier of the component to shadow.

target - the identifier of the component that will shadow the source component.

Throws:

NullPointerException - if either argument is null.

UnrecognizedComponentException - if either argument is not a recognisable ComponentID object for the SLEE or does not correspond with a component installed in the SLEE.

InvalidArgumentException - if the component type of source does not support shadowing, if source is a linked component, or if creating the shadow would generate a cyclic dependency between shadowed and linked components.

InvalidStateException - if source is already shadowed, or if source currently has an install level of DEPLOYED.

ManagementException - if the component could not be shadowed due to a system-level failure.

Since:

Rhino 2.4.0

unshadowComponent

void unshadowComponent(ComponentID id)
                throws NullPointerException,
                       UnrecognizedComponentException,
                       InvalidArgumentException,
                       InvalidStateException,
                       ManagementException

Remove the shadow from a shadowed component.

Only components with an install level of InstallLevel.INSTALLED may be unshadowed. If the install level of id is VERIFIED, then this method will automatically unverify the component (and any relevant dependent components) before removing the shadow. A component with an install level of InstallLevel.DEPLOYED must be manually undeployed first before it can be unshadowed.

Parameters:

id - the identifier of the shadowed component.

Throws:

NullPointerException - if id is null.

UnrecognizedComponentException - if id is not a recognisable ComponentID object for the SLEE or it does not correspond with a component installed in the SLEE.

InvalidArgumentException - if id does not correspond with a shadowed component.

InvalidStateException - if id currently has an install level of DEPLOYED.

ManagementException - if the component shadow could not be removed due to a system-level failure.

Since:

Rhino 2.4.0

getDeployableUnit

byte[] getDeployableUnit(DeployableUnitID id)
                  throws NullPointerException,
                         UnrecognizedDeployableUnitException,
                         ManagementException

Get the contents of the specified deployable unit jar file.

Parameters:

id - the identifier of the deployable unit.

Returns:

a byte[] containing the binary contents of the deployable unit jar file.

Throws:

NullPointerException - if id is null.

UnrecognizedDeployableUnitException - if id is not a recognizable DeployableUnitID for the SLEE or it does not correspond with a deployable unit installed in the SLEE.

ManagementException - if the deployable unit jar file contents could not be obtained due to a system-level failure.

getDescriptor

ComponentDescriptor getDescriptor(ComponentID id)
                           throws NullPointerException,
                                  UnrecognizedComponentException,
                                  ManagementException

Get the component descriptor for a component identifier.

Links and Shadows

This method does not follow links and shadows. The descriptor returned is for the exact component specified by the id argument.

Vendor Data

This method adds vendor-specific data in the returned descriptor object. The type of this vendor-specific data depends on the type of component:

• For a linked component, the vendor-specific data will be of type LinkedComponentDescriptorExtensions.

• For any other component, the vendor-specific data will be of type ComponentDescriptorExtensions.

Specified by:

getDescriptor in interface DeploymentMBean

Parameters:

id - the identifier of the component.

Returns:

the component descriptor for the component.

Throws:

NullPointerException - if id is null.

UnrecognizedComponentException - if id is not a recognizable ComponentID object for the SLEE or it does not correspond with a component installed in the SLEE.

ManagementException - if the descriptor could not be obtained due to a system-level failure.

getDescriptor

DeployableUnitDescriptor getDescriptor(DeployableUnitID id)
                                throws NullPointerException,
                                       UnrecognizedDeployableUnitException,
                                       ManagementException

Get the deployable unit descriptor for a deployable unit.

Vendor Data

This method adds vendor-specific data in the returned descriptor object. The type of this vendor-specific data is DeployableUnitDescriptorExtensions.

Specified by:

getDescriptor in interface DeploymentMBean

Parameters:

id - the identifier of the deployable unit.

Returns:

the deployable unit descriptor for the deployable unit.

Throws:

NullPointerException - if id is null.

UnrecognizedDeployableUnitException - if id is not a recognizable DeployableUnitID object for the SLEE or it does not correspond with a deployable unit installed in the SLEE.

ManagementException - if the descriptor could not be obtained due to a system-level failure.

isInstalled

boolean isInstalled(ComponentID id)
             throws NullPointerException,
                    ManagementException

Specified by:

isInstalled in interface DeploymentMBean

Throws:

NullPointerException

ManagementException

isInstalled

boolean isInstalled(DeployableUnitID id)
             throws NullPointerException,
                    ManagementException

Specified by:

isInstalled in interface DeploymentMBean

Throws:

NullPointerException

ManagementException

getSbbs

SbbID[] getSbbs(ServiceID service)
         throws NullPointerException,
                UnrecognizedServiceException,
                ManagementException

Specified by:

getSbbs in interface DeploymentMBean

Throws:

NullPointerException

UnrecognizedServiceException

ManagementException

getDescriptors

ComponentDescriptor[] getDescriptors(ComponentID[] ids)
                              throws NullPointerException,
                                     ManagementException

Specified by:

getDescriptors in interface DeploymentMBean

Throws:

NullPointerException

ManagementException

getDescriptors

DeployableUnitDescriptor[] getDescriptors(DeployableUnitID[] ids)
                                   throws NullPointerException,
                                          ManagementException

Specified by:

getDescriptors in interface DeploymentMBean

Throws:

NullPointerException

ManagementException

getDeployableUnit

DeployableUnitID getDeployableUnit(String url)
                            throws NullPointerException,
                                   UnrecognizedDeployableUnitException,
                                   ManagementException

Specified by:

getDeployableUnit in interface DeploymentMBean

Throws:

NullPointerException

UnrecognizedDeployableUnitException

ManagementException

getReferringComponents

ComponentID[] getReferringComponents(ComponentID id)
                              throws NullPointerException,
                                     UnrecognizedComponentException,
                                     ManagementException

Get the set of components that use or make reference to a specified component. For example, if an SBB identified by the SbbID sbb uses a profile specification identified by the ProfileSpecificationID profSpec, the array returned from getReferringComponents(profSpec) will contain sbb.

Links and Shadows

This method does not follow links and shadows. The returned component array indicates the components that refer directly to the exact component specified by the id argument.

Incoming links and shadows are not reported by this method. If other components link to id, or if id shadows other components, these relationships may be discovered using the vendor-specific data included in the component’s component descriptor.

Specified by:

getReferringComponents in interface DeploymentMBean

Returns:

an array of component identifiers for the components that use or make reference to the component identified by id.

Throws:

NullPointerException - if id is null.

UnrecognizedComponentException - if id is not a recognizable ComponentID object for the SLEE or it does not correspond with a component installed in the SLEE.

ManagementException - if the identifiers could not be obtained due to a system-level failure.

getSbbParts

SbbPartID[] getSbbParts()
                 throws ManagementException

Get the set of SBB parts installed in the SLEE.

Returns:

an array of SBB part identifiers.

Throws:

ManagementException - if the identifiers could not be obtained due to a system-level failure.

Since:

Rhino 2.4.0

getBindingDescriptors

BindingDescriptorID[] getBindingDescriptors()
                                     throws ManagementException

Get the set of binding descriptors installed in the SLEE.

Returns:

an array of binding descriptor identifiers.

Throws:

ManagementException - if the identifiers could not be obtained due to a system-level failure.

Since:

Rhino 2.4.0

getRhinoPolicy

String[] getRhinoPolicy(int[] nodes)
                 throws ManagementException

Returns the currently active JVM security policies for the specified nodes. The return result will have one security policy per node specified, in the same order the nodes were specified. This method is mainly intended for diagnostic purposes as the information returned cannot be edited directly.

Throws:

ManagementException - if an internal error occurs

getSecurityPolicy

String getSecurityPolicy(ComponentID id,
                         String subId,
                         boolean original)
                  throws NullPointerException,
                         UnrecognizedComponentException,
                         IllegalArgumentException,
                         ManagementException

Returns the current or original security policy associated with the specified component. Note that the returned policy for ServiceIDs and SbbIDs may be shared with other components. Security permissions apply to individual jar files, so if there are multiple SBBs in a single jar they will all share the same security permissions.

An optional 'subId' may be specified when querying the permissions of a Library to return permissions of a jar contained within the Library (rather than the security permissions of the Library itself). When querying a Library, this argument should equal the jarname as specified in the LibraryDescriptor. Passing a non-null subId will cause an IllegalArgumentException to be thrown for non-LibraryID component IDs.

Parameters:

id - the ID of the component to query

subId - an optional sub identifier (should usually be null).

original - if true, the original security policy for the component will be returned.

Returns:

the current or original security policy for the specified component.

Throws:

NullPointerException - if id is null

UnrecognizedComponentException - if the 'id' component cannot be found.

IllegalArgumentException - if an unsupported component ID was specified

ManagementException - if an internal error occurred

setSecurityPolicy

void setSecurityPolicy(ComponentID id,
                       String subId,
                       String policyText)
                throws NullPointerException,
                       UnrecognizedComponentException,
                       IllegalArgumentException,
                       ManagementException

Set the security policy for the specified component. This will override the security policy obtained from the component’s deployment descriptor.

An optional 'subId' may be specified when setting the permissions of a Library to set permissions of a jar contained within the Library (rather than the security permissions of the Library itself). When specifying a Library, this argument should equal the jarname as specified in the LibraryDescriptor. Passing a non-null subId will cause an IllegalArgumentException to be thrown for non-LibraryID component IDs.

Parameters:

id - the ID of the component to modify

subId - an optional sub identifier (should usually be null).

policyText - the new text of the security policy

Throws:

NullPointerException - if 'id' or 'policyText' is null.

UnrecognizedComponentException - if the 'id' component cannot be found.

IllegalArgumentException - if the policy text failed to parse correctly

ManagementException - if an internal error occurred

getEnvEntries

Map<String,String> getEnvEntries(ComponentID id,
                                 boolean original)
                          throws NullPointerException,
                                 UnrecognizedComponentException,
                                 ManagementException,
                                 IllegalArgumentException

Returns a Map containing String representations of the env entries for the specified component.

Parameters:

id - the ID of the component to query

original - if true, the original env entries for the component will be returned.

Returns:

the current or original env entries for the specified component.

Throws:

NullPointerException - if 'id' is null.

UnrecognizedComponentException - if the 'id' component cannot be found

ManagementException - if an internal error occurred

IllegalArgumentException - if an illegal ComponentID type was specified

setEnvEntries

void setEnvEntries(ComponentID id,
                   Map<String,String> entries)
            throws NullPointerException,
                   UnrecognizedComponentException,
                   ManagementException,
                   IllegalArgumentException,
                   InvalidArgumentException

Sets the env entries for the specified component.

This method will throw an InvalidArgumentException if an illegal argument is found in the entries map. This can occur when the String value supplied is unparseable for the type of the env entry represented by the map entry’s key.

Parameters:

id - the ID of the component to modify

entries - the new env entries to use

Throws:

NullPointerException - if 'id' or entries is null

UnrecognizedComponentException - if the 'id' component cannot be found.

ManagementException - if an internal error occurred

IllegalArgumentException - if an illegal ComponentID type was specified, or if an unrecognized env entry key is supplied

InvalidArgumentException - if an invalid value for an entry was found

auditComponent

ComponentAuditResult auditComponent(ComponentID id)
                             throws NullPointerException,
                                    UnrecognizedComponentException,
                                    InvalidStateException,
                                    ManagementException

Audit a component and its dependencies for potential classloader problems.

The audit will look for the following problems:

• A component class that references a class that cannot be loaded via its classloader dependency graph. This may cause ClassNotFoundException or NoClassDefFoundError exceptions to occur at runtime.

• A component class that references a class that can be loaded from more than one dependent component through different classloader dependency graphs. This may cause ClassCastException or LinkageError exceptions to occur at runtime.

Parameters:

id - the component identifier of the component to audit.

Returns:

the audit result.

Throws:

NullPointerException - if id is null.

UnrecognizedComponentException - if id is not a recognizable ComponentID object for the SLEE or it does not correspond with a component installed in the SLEE.

InvalidStateException - if the specified component does not have an install level of at least InstallLevel.VERIFIED.

ManagementException - if the audit could not be completed due to a system-level failure.

Since:

Rhino 2.5.0

getSasBundle

String getSasBundle()
             throws ManagementException

Creates a SAS Bundle by inspecting all deployed deployable units.

Returns:

the combined bundle from the SAS configuration and deployed mini-bundles in the current namespace

Throws:

ManagementException - if an error occurs generating the merged bundle