org.glassfish.paas.orchestrator.service.spi
Interface ServicePlugin<T extends ServiceType>

@Contract
public interface ServicePlugin<T extends ServiceType>

An SPI to allow the adding of multiple service provider implementations into the PaaS runtime. Each Plugin supports a Service of a particular ServiceType

Each Plugin provides its own implementation of ServiceDescription and ProvisionedService.

A Plugin for a Service implementation performs the following functions:

Service Dependency Discovery
• provides explicit service dependencies from an application to a service
• discovers implicit and discovered service dependencies of an application and helps the orchestrator in finding out the effective set of service dependencies of the application
• Service Provisioning and Service Association
• provisions/decomissions a Service
• associates/disassociates a target ProvisionedService from/to a source ProvisionedService

Author:

Sivakumar Thyagarajan

Method Summary

void	associateServices(Service serviceConsumer, ServiceReference svcRef, Service serviceProvider, boolean beforeDeployment, PaaSDeploymentContext dc) A ProvisionedService for a ServiceReference is associated with another ProvisionedService through this method.
boolean	deploy(PaaSDeploymentContext dc, Service service) Deploy the orchestration-enabled archive.
void	dissociateServices(Service serviceConsumer, ServiceReference svcRef, Service serviceProvider, boolean beforeUndeploy, PaaSDeploymentContext dc) A ProvisionedService for a ServiceReference is dis-associated from another ProvisionedService through this method.
ServiceDescription	getDefaultServiceDescription(String appName, ServiceReference svcRef) For a discovered (implicit) ServiceReference, the application developer may not have provided corresponding ServiceDefinitions to satisfy the ServiceReference.
Set<ServiceDescription>	getImplicitServiceDescriptions(ReadableArchive cloudArchive, String appName, PaaSDeploymentContext context) OE gets implicit ServiceDescription associated with an application from the Plugin through this method, if the application does not have explicit ServiceDescriptions in its services metadata deployment descriptor, for the type supported by the Plugin.
ProvisionedService	getProvisionedService(ServiceDescription serviceDescription, ServiceInfo serviceInfo) When CPAS is restarted, the CPAS uses this method to get the ProvisionedService that were provisioned earlier through the plugin.
Set<ServiceReference>	getServiceReferences(String appName, ReadableArchive cloudArchive, PaaSDeploymentContext dc) Discover the implicit service references in the orchestration enabled archive.
T	getServiceType() Provides the ServiceType supported by this plugin
boolean	handles(ReadableArchive cloudArchive) Checks if this plugin can process and handle the provided orchestration enabled archive
boolean	handles(ServiceDescription serviceDescription) Checks if this plugin can handle the specified service-description
boolean	isReferenceTypeSupported(String referenceType) Checks if a service reference of a particular ref-type can be supported by a service that this plugin can provision.
boolean	isRunning(ProvisionedService provisionedSvc) Checks if a ProvisionedService is still running (ie ping service).
ProvisionedService	match(ServiceReference svcRef) Given a ServiceReference, find if a Service has already been provisioned for it.
ProvisionedService	provisionService(ServiceDescription serviceDescription, PaaSDeploymentContext paasDC) Once the CPAS merges all discovered and explicit ServiceDefinitionss, it provisions the required Services through the Plugin.
boolean	reassociateServices(Service svcConsumer, Service oldSvcProvider, Service newSvcProvider, ServiceOrchestrator.ReconfigAction reason) When a Service has been re-provisioned, and a prior deployment has already been bound to the earlier ProvisionedService, CPAS uses this method to reassociate resources of the "Service Consumer" ProvisionedService to point to the new "Service Provider" ProvisionedService.
boolean	reconfigureServices(ProvisionedService oldPS, ProvisionedService newPS) When a Service has been re-provisioned, and a prior deployment has already been bound to the earlier ProvisionedService, CAS uses this method to reassociate resources to point to the newly ProvisionedService
ProvisionedService	scaleService(ProvisionedService provisionedService, int scaleCount, AllocationStrategy allocStrategy) Scales the size of a Service up or down as per the provided scalingFactor.
ProvisionedService	startService(ServiceDescription serviceDescription, ServiceInfo serviceInfo) Start a Service that had been provisioned earlier and is now Stopped.
boolean	stopService(ProvisionedService provisionedService, ServiceInfo serviceInfo) Stop a ProvisionedService.
boolean	undeploy(PaaSDeploymentContext dc, Service service) Undeploy the orchestration-enabled archive.
boolean	unprovisionService(ServiceDescription serviceDescription, PaaSDeploymentContext dc) During undeployment of an application, OE decommissions the Services that are scoped to the application.

Method Detail

getServiceType

T getServiceType()

Provides the ServiceType supported by this plugin

Returns:

the ServiceType supported by this plugin

handles

boolean handles(ReadableArchive cloudArchive)

Checks if this plugin can process and handle the provided orchestration enabled archive

Returns:

true if the plugin can handle service provisioning for this archive, false otherwise

handles

boolean handles(ServiceDescription serviceDescription)

Checks if this plugin can handle the specified service-description

Parameters:

serviceDescription - service-description to be handled

Returns:

true if the plugin can handle service provisioning for this service-description, false otherwise

isReferenceTypeSupported

boolean isReferenceTypeSupported(String referenceType)

Checks if a service reference of a particular ref-type can be supported by a service that this plugin can provision.

For instance, if a Java EE application required a javax.sql.Datasource service reference, the DB plugin would indicate that it could support that service ref-type.

getServiceReferences

Set<ServiceReference> getServiceReferences(String appName,
                                           ReadableArchive cloudArchive,
                                           PaaSDeploymentContext dc)

Discover the implicit service references in the orchestration enabled archive. For instance, a orchestration.xml may not explicitly provide a RDBMS ServiceType ServiceDescription and a ServiceReference for a JDBC connection pool and resource used by the application. The plugin could figure out that a RDBMS ServiceType service reference is implicit in the application by virtue of the application having a reference to a JDBC resource in component deployment descriptors (web.xml, sun-web.xml)

Parameters:

appName - application-name as generated by deployment framework.

cloudArchive - the orchestration-enabled archive for which the CAS needs to determine implicit ServiceReferences

dc - PaaS deployment context

Returns:

A Set of ServiceReferences required to be satisfied for the proper functioning of the orchestration-enabled archive

getDefaultServiceDescription

ServiceDescription getDefaultServiceDescription(String appName,
                                                ServiceReference svcRef)

For a discovered (implicit) ServiceReference, the application developer may not have provided corresponding ServiceDefinitions to satisfy the ServiceReference. Since the Service Provisioning layer works with concrete ServiceDefinitions to provision a service, the CAS uses this method to obtain a ServiceDescription, defaulted to known values, for a ServiceReference. ServiceReference can also be modified to fill in additional details. For eg., default jdbc-connection-pool properties.

Returns:

A valid ServiceDescription with defaults filled in.

getImplicitServiceDescriptions

Set<ServiceDescription> getImplicitServiceDescriptions(ReadableArchive cloudArchive,
                                                       String appName,
                                                       PaaSDeploymentContext context)

OE gets implicit ServiceDescription associated with an application from the Plugin through this method, if the application does not have explicit ServiceDescriptions in its services metadata deployment descriptor, for the type supported by the Plugin.

Parameters:

cloudArchive - The application archive

appName - The application Name

Returns:

A Set of implicit ServiceDescriptions that this Plugin "implies" for the provided application archive.

provisionService

ProvisionedService provisionService(ServiceDescription serviceDescription,
                                    PaaSDeploymentContext paasDC)

Once the CPAS merges all discovered and explicit ServiceDefinitionss, it provisions the required Services through the Plugin. The Plugin is responsible for ensuring that the provisioning action is atomic. That is, the Service that is being provisioned must be completely provisioned or not at all.

Parameters:

serviceDescription - ServiceDescription that will be used to provision a service.

paasDC - PaaSDeploymentContext that provides application deployment context

Returns:

a Set of ProvisionedServices

getProvisionedService

ProvisionedService getProvisionedService(ServiceDescription serviceDescription,
                                         ServiceInfo serviceInfo)

When CPAS is restarted, the CPAS uses this method to get the ProvisionedService that were provisioned earlier through the plugin.

Parameters:

serviceDescription - ServiceDescription for the service dependency.

serviceInfo - The ServiceInfo persisted in the configuration store for the ProvisionedService

Returns:

A ProvisionedService instance that represents details about the provisioned service.

unprovisionService

boolean unprovisionService(ServiceDescription serviceDescription,
                           PaaSDeploymentContext dc)

During undeployment of an application, OE decommissions the Services that are scoped to the application. The Orchestrator uses this method to let the plugin decommission a Service provisioned by it. The plugin stops the Service and then performs any cleanup required for a service to be decomissioned. It should be noted that the state of the Service may be lost as part of the decomissioning process. [for instance the data in a Database may be lost during application undeployment unless the user explicitly indicates that undeployment must retain prior state or the Service provider implementation provides a mechanism to persist the State before destroying the Service.]

Parameters:

serviceDescription - The ServiceDescription associated with the provisioned service that needs to be decommissioned.

dc - The DeploymentContext associated with the undeployment operation that initiated this decomissioning process.

Returns:

true if the Service was successfully unprovisioned, false otherwise.

scaleService

ProvisionedService scaleService(ProvisionedService provisionedService,
                                int scaleCount,
                                AllocationStrategy allocStrategy)

Scales the size of a Service up or down as per the provided scalingFactor.

Parameters:

provisionedService - Existing ProvisionedService

scaleCount - Number of units of the Service that needs to be scaled. A positive number for scaling up and a negative number for scaling down.

allocStrategy - The allocationStrategy that needs to be utilized to scale the Service. The allocationStrategy implementation that is provided could be used to spawn a new instance in a less-loaded/underutilized machine in the ServerPool. This could be null, if the default allocation strategy needs to be employed.

Returns:

the new ProvisionedService scaling operation was successful

associateServices

void associateServices(Service serviceConsumer,
                       ServiceReference svcRef,
                       Service serviceProvider,
                       boolean beforeDeployment,
                       PaaSDeploymentContext dc)

A ProvisionedService for a ServiceReference is associated with another ProvisionedService through this method. See the section on "Service Association/Binding" at http://wikis.sun.com/display/GlassFish/3.2+Service+Orchestration+One+Pager for more information.

Parameters:

serviceConsumer - The "target" ProvisionedService

svcRef - The ServiceReference that binds the "source" and "target" ServiceReferences.

serviceProvider - The "source" ProvisionedService

beforeDeployment - Indicates if this association is happening before the deployment of the application

dc - The DeploymentContext associated with the application deployment or enablement that caused this association

dissociateServices

void dissociateServices(Service serviceConsumer,
                        ServiceReference svcRef,
                        Service serviceProvider,
                        boolean beforeUndeploy,
                        PaaSDeploymentContext dc)

A ProvisionedService for a ServiceReference is dis-associated from another ProvisionedService through this method. See the section on "Service Association/Binding" at http://wikis.sun.com/display/GlassFish/3.2+Service+Orchestration+One+Pager for more information.

Parameters:

serviceConsumer - The "target" ProvisionedService

svcRef - The ServiceReference that bound the "source" and "target" ServiceReferences.

serviceProvider - The "source" ProvisionedService

beforeUndeploy - Indicates if this dis-association is happening before the deployment of the application

dc - The DeploymentContext associated with the application undeployment or disablement that caused this dis-association

deploy

boolean deploy(PaaSDeploymentContext dc,
               Service service)

Deploy the orchestration-enabled archive. At present, the deployment to the provisioned GlassFish Service is performed by the deployment infrastructure in CPAS/DAS. In the future, when we support non-Java EE archives that the deployment infrastructure cannot control, OE would invoke this method in the plugin to initiate deployment of the archive in that container service.

Parameters:

dc - PaaSDeploymentContext

service - Service to which deployment needs to be done.

Returns:

boolean status indicating whether deployment was successful.

undeploy

boolean undeploy(PaaSDeploymentContext dc,
                 Service service)

Undeploy the orchestration-enabled archive. At present, the undeploying an application in a provisioned GlassFish Service is performed by the deployment infrastructure in CPAS/DAS. In the future, when we support non-Java EE archives that the deployment infrastructure cannot control, OE would invoke this method in the plugin to initiate undeployment of the archive in that container service.

Parameters:

dc - PaaSDeploymentContext

service - Service to which deployment needs to be done.

Returns:

boolean status indicating whether undeployment was successful.

startService

ProvisionedService startService(ServiceDescription serviceDescription,
                                ServiceInfo serviceInfo)

Start a Service that had been provisioned earlier and is now Stopped.

Parameters:

serviceDescription - The ServiceDescription of the Service that needs to be started

serviceInfo - The ServiceInfo that captures the prior provisioning state of the Service

Returns:

A reference to the started Service.

stopService

boolean stopService(ProvisionedService provisionedService,
                    ServiceInfo serviceInfo)

Stop a ProvisionedService.

Parameters:

provisionedService - The ProvisionedService of the Service that needs to be stopped

serviceInfo - The ServiceInfo that captures the provisioned state of the Service

Returns:

True if the Service was successfully stopped, False otherwise.

isRunning

boolean isRunning(ProvisionedService provisionedSvc)

Checks if a ProvisionedService is still running (ie ping service). This could be used by CAS, in scenarios where the CAS is restarted, but the Provisioned Services are still available for an application to be used and no fresh provisioning of Services needs to be done.

match

ProvisionedService match(ServiceReference svcRef)

Given a ServiceReference, find if a Service has already been provisioned for it.

reconfigureServices

boolean reconfigureServices(ProvisionedService oldPS,
                            ProvisionedService newPS)

When a Service has been re-provisioned, and a prior deployment has already been bound to the earlier ProvisionedService, CAS uses this method to reassociate resources to point to the newly ProvisionedService

reassociateServices

boolean reassociateServices(Service svcConsumer,
                            Service oldSvcProvider,
                            Service newSvcProvider,
                            ServiceOrchestrator.ReconfigAction reason)

When a Service has been re-provisioned, and a prior deployment has already been bound to the earlier ProvisionedService, CPAS uses this method to reassociate resources of the "Service Consumer" ProvisionedService to point to the new "Service Provider" ProvisionedService. Some of the reasons reconfiguration may occur are auto-scaling of Services, CPAS or VM restarts.

Parameters:

svcConsumer - The Service Consumer ProvisionedService

oldSvcProvider - The old Service Provider ProvisionedService

newSvcProvider - The new Service Provider ProvisionedService

reason - The reason for the re-configuration.