Preface

This document describes the functionality provided by the WebLogic server (WLS) plugin.

See the Deployit Reference Manual for background information on Deployit and deployment concepts.

Overview

The WLS plugin is a Deployit plugin that adds capability for managing deployments and resources on WebLogic server. It works out of the box for deploying/ undeploying application artifacts, datasource and other JMS resources (see the Features section below) , and can easily be extended to support more deployment options or management of new artifacts/resources on WLS.

Features

• Deployment units
  • Enterprise application (EAR)
  • Web application (WAR)
  • Enterprise JavaBean (EJB)
  • J2EE library
• Staging modes
  • Stage
  • Nostage
• Redeployment strategies
  • Classical
  • Side by side
• Resources
  • Datasource
  • JMS Queue
  • JMS uniform distributed Queue
  • JMS connection factory
  • Mail Session
• Discovery

Requirements

• Deployit requirements

  • Deployit: versioned 3.5
  • WLS versions: WLS 9.x, WLS 10.3, WLS 11g (Unix and Windows)
  • Other Deployit Plugins: None

• Infrastructural requirements

  • WebLogic Domain user credentials
  • User credentials for accessing the Host managing the WebLogic Administration Server.
  • User credentials for accessing target Hosts of managed Servers (for NoStage mode)

Usage in Deployment Packages

The plugin works with the standard deployment package of DAR format. Please see the Packaging Manual for more details about the DAR format and the ways to compose one.

The following is a sample MANIFEST.MF file that can be used to create a WebLogic specific deployment package. It contain declarations for an Ear, a datasource and a couple of JMS resources.

Manifest-Version: 1.0
Deployit-Package-Format-Version: 1.3
CI-Application: SampleApp
CI-Version: 1.0

Name: SampleApp-1.0.ear
CI-Name: SampleApp
CI-Type: jee.Ear

Name: testDatasource
CI-Type: wls.DataSourceSpec
CI-jndiNames: jdbc/sampleDatasource
CI-url: jdbc:mysql://localhost/test
CI-driverName: com.mysql.jdbc.Driver
CI-username: {{DATABASE_USERNAME}}
CI-password: {{DATABASE_PASSWORD}}

Name: sampleQueue
CI-Type: wls.QueueSpec
CI-jndiNames: jms/testQueue
CI-jmsModuleName: {{JMS_MODULE_NAME}}

Name: sampleCf
CI-Type: wls.ConnectionFactorySpec
CI-jndiNames: jms/sampleCf
CI-jmsModuleName: {{JMS_MODULE_NAME}}

Using the deployables and deployeds

The following table describes which deployable/container combinations are possible.

Deployable vs. Container table

The following table describes the effect a deployed has on it's container

Deployed Actions Table

Deploying applications

The way an application is deployed to a container can be influenced by modifying properties of the corresponding deployed.

For example, if an Ear is to be deployed as a versioned application, using nostage mode, specify these properties in the deployed EarModule:

• versioned = true (or on UI, check the checkbox)
• stage mode = NoStage (or on UI, choose NoStage from the dropdown)
• staging directory = absolute path of the directory where Ear is to be uploaded

Similarly, if the deployed application needs to be upgraded using the side by side redeployment strategy, modify these properties in the deployed EarModule:

• staging directory = new path of the directory where the new version of Ear will be uploaded
• redeployment strategy = SIDE_BY_SIDE (or on the UI, choose SIDE_BY_SIDE from the dropdown)
• retire timeout = Time interval (seconds) if a timeout period is needed for retiring the previous version of the application

Note about targeting to multiple containers

Certain deployables can be targeted to multiple containers. For example, an Ear can be targeted to two clusters. Similarly a datasource can be targeted to two clusters.

Note that the way WLS plugin handles this multiple targeting is by generating steps for each targeting. So for example, if a datasource is targeted to two cluster (say Cluster-1, Cluster-2) , Deployit will create two datasource creation steps, wherein.

• The first step will create the datasource on Cluser-1, with all the properties of the deployed datasource.
• The second step will add Cluster-2 to the target list of the datasource created in first step. If there are difference in the datasource values of this deployed, it overrides the previous value.

Since the second targeting overrides the properties of the first targeting, take utmost care to keep the properties of the deployeds (of the same deployable) uniform across each other.

Similar to creation, the following sequence of steps occurs if destroy operation takes place for such a multiple targeted datasource:

• The first step will remove Cluster-1 from datasource target's list
• The second step will remove Cluster-2 from datasource target's list, and since the datasource has no target set on it, it destroys the datasouce.

Note that the actual datasource destruction takes place in the second step, and the first step simply removes the first container from datasource targets.

Creating resources

Deployit handles the creation of resources in the same way it handles deploying an application. Refer to Reference Manual for more details on deploying resources.

Note about managing JMS resources

The WLS plugin greatly simplifies the management of JMS resources. It does this by automatically managing the JMS modules and sub-deployments needed for JMS resources, letting the user to focus on the actual JMS resource he needs to manage. For example, the followings is the sequence of steps that happens behind the scene when a JMS resource like Queue is created:

• the JMS module name is specified by user in deployed resource (look at 'jmsModuleName' property in Queue for example)
• plugin automatically creates the module if it is not present, otherwise adds the deployed container to existing module targets
• plugin automatically creates a subdeployment if is not present, otherwise adds the deployed container to existing subdeployment targets
• plugin creates/updates the JMS resource and assign the subdeployment created in previous step as the resource subdeployment

Similarly, the destruction of a JMS resource is handled behind the scene in the following way:

• the resource container is removed from it's subdeployment targets.
• destroys the JMS resource only if it's subdeployment targets list is empty (if it's the last one)
• destroys the subdeployment automatically if it contains no targets
• destroy JMS module if no other JMS resources are using it.

The thing to note is that the WLS plugin manage modules intelligently unless you want to use your own.

Extension points

TThe WLS plugin is designed to be extended through Deployit's Plugin API type system and through the use of custom user defined WLST Python scripts. Refer to Customization Manual for an explanation of the type system.

The WLS plugin associates Create, Modify and Destroy operations received from Deployit with WLST Python scripts that need to be executed for the operation. The operation specific script is given a Python object representation of the Deployed that triggered the operation. The script is then executed using WLST on the target Domain. Below, for example is the definition of wls.Datasource in synthetic.xml:

<type type="wls.DataSource" extends="wls.Resource" deployable-type="wls.DataSourceSpec" description="An object bound to the 
                              JNDI tree that provides database connectivity through a pool of JDBC connections">
    <generate-deployable type="wls.DataSourceSpec" extends="wls.ResourceSpec" description="Specification for a datasource"/>
    <property name="additionalPropertiesNotToExpose" hidden="true" default="jndiNames, url, driverName, username, 
                                            password, properties"/>

    <property name="createScript" default="wls/ds/create-datasource.py" hidden="true" />

    <property name="destroyScript" default="wls/ds/destroy-datasource.py"  hidden="true" />

    <property name="jndiNames" description="JNDI path to where this data source is bound" />
    <property name="url" description="URL of the database to connect to." />
    <property name="driverName" description="Full package name of JDBC driver class used to create the physical 
              database connections in the connection pool" />
    <property name="username" description="Username attribute passed to the JDBC driver when creating 
              physical database connections" />
    <property name="password" password="true" description="Password attribute passed to the 
              JDBC driver when creating physical database connections" />
</type>

The script has all the information from the Deployed at its disposal to translate into the WLST API calls needed to configure WebLogic. The following sample Python snippet is using deployed to create a datasource:

cmo.createJDBCSystemResource(deployed.name)
datasourcePath = '/JDBCSystemResources/%s/JDBCResource/%s' % (deployed.name, deployed.name)
cd(datasourcePath)
cd('%s/JDBCDriverParams/%s' % (datasourcePath, deployed.name))
set("Url", deployed.url)
set("DriverName", deployed.driverName)
set('Password', deployed.password)
# use jmsModuleName, jmsServer and jndiName to create the queue

The WLS plugin also offers the ability to influence the order in which scripts are executed in relation to other Deployed operations. The order allows for the chaining of scripts to create a logical sequence of events. For example, the following synthetic.xml snippet says that creation of the queue (order = 60) will happen before deployment of the Ear (order = 70), and the destruction of the queue (order = 40) will take place the after undeployment of the Ear (order = 30)

<type type="wls.EarModule" extends="wls.ExtensibleDeployedArtifact" deployable-type="jee.Ear" description="Ear 
                                            with values configured for a deployment">
    <generate-deployable type="wls.Ear" extends="jee.Ear" description="A JEE EAR archive"/>
    <property name="createScript" default="wls/application/deploy-application.py" hidden="true"/>
    <property name="createVerb" default="Deploy" hidden="true" />
    <property name="createOrder" kind="integer" default="70" hidden="true" />

    <property name="destroyScript" default="wls/application/undeploy-application.py" hidden="true"/>
    <property name="destroyVerb" default="Undeploy" hidden="true" />
    <property name="destroyOrder" kind="integer" default="30" hidden="true" />

    <property name="startScript" default="wls/application/start-application.py" hidden="true"/>
    <property name="startOrder" kind="integer" default="90" hidden="true" />

    <property name="stopScript" default="wls/application/stop-application.py" hidden="true"/>
    <property name="stopOrder" kind="integer" default="10" hidden="true" />
</type>

<type type="wls.Queue" extends="wls.AbstractQueue" deployable-type="wls.QueueSpec" 
      description="A point-to-point destination type">
    <generate-deployable type="wls.QueueSpec" extends="wls.JmsResourceSpec" description="Specification for a JMS Queue"/>
    <property name="createScript" default="wls/jms/create-queue.py" hidden="true"/>
    <property name="createVerb" default="Create" hidden="true" />
    <property name="createOrder" kind="integer" default="60" hidden="true" />

    <property name="destroyScript" default="wls/jms/destroy-queue.py" hidden="true"/>
    <property name="destroyVerb" default="Destroy" hidden="true" />
    <property name="destroyOrder" kind="integer" default="40" hidden="true" />

    <property name="setErrorDestinationScript" default="wls/jms/set-error-queue.py" hidden="true"/>
    <property name="unsetErrorDestinationScript" default="wls/jms/unset-error-queue.py" hidden="true"/>
</type>

Next section describes the extensibility by examples:

Extending the Plugin (A Tutorial)

Hiding an existing property from a deployed/deployable

The following synthetic.xml snippet shows how JDBCConnectionPoolParams_CapacityIncrement property in wls.Datasource can be made hidden giving it a default value of 2.

<type-modification type="wls.DataSource">
    <!-- makes the propery hidden from the UI -->
  <property name="JDBCConnectionPoolParams_CapacityIncrement"  category="Connection Pool" label="Capacity Increment" 
         kind="integer" hidden="true" default="2"/>
</type-modification>

Adding a new property to a deployed/deployable

The following synthetic.xml snippet shows how a new property inactiveConnectionTimeoutSeconds can be added to wls.Datasource

<type-modification type="wls.DataSource">
    <!-- adding new property -->
    <property name="JDBCConnectionPoolParams_InactiveConnectionTimeoutSeconds"  category="Connection Pool" 
             label="Inactive Connection Timeout (sec)" kind="integer" description="inactive Connection Timeout in Seconds" />
</type-modification>    

Note that while adding a new property in WLS plugin, the property name should correspond to the relative path of the property (file) from the configuration item in WLST (minus the type name). For example, since the relative path of property InactiveConnectionTimeoutSeconds in WLST is {datasource-name}/JDBCConnectionPoolParams/{datasource-name}/InactiveConnectionTimeoutSeconds, the property name to use while adding a new property is JDBCConnectionPoolParams_InactiveConnectionTimeoutSeconds.

Adding a new type

The following synthetic.xml snippet shows the definition of a new CI type wls.WorkManager. Since it's a resource and it can be targeted to a Cluster or a Server, it has been made to extend wls.Resource

<type type="wls.WorkManager" extends="wls.Resource" deployable-type="wls.WorkManagerSpec">
    <generate-deployable type="wls.WorkManagerSpec" extends="wls.ResourceSpec"/>
        <property name="createScript" default="wls/env/create-work-manager.py" hidden="true" />
    <property name="destroyScript" default="wls/env/destroy-work-manager.py" hidden="true" />
</type>

The name property is automatically added to all CIs so it has not been defined explicitly as a property. Additional properties can be added in the definition as per the need.

Next step involves adding the Python scripts for the steps. For the `wls.WorkManager' example, two Python scripts needs to be created: create-work-manager.py and destroy-work-manager.py

wls/env/create-work-manager.py

workManagerPath='/SelfTuning/%s/WorkManagers/%s' %(deployed.container.domain.name, deployed.name)
connectAndEdit()

  if exists(workManagerPath):
    print 'Modifying work manager %s for target %s' % (deployed.name, deployed.container.name)
    setOrOverride = overrideWithWarning
else:
    print 'Creating work manager %s for target %s' % (deployed.name, deployed.container.name)
    cd('/SelfTuning/' + deployed.container.domain.name + '/WorkManagers')
    cmo.createWorkManager(deployed.name)
    setOrOverride = set

cd(workManagerPath)
newTargets = []
for t in get('Targets'):
    newTargets.append(t)

newTargets.append(ObjectName(deployed.container.objectName))
set('Targets', jarray.array(newTargets, ObjectName))

saveAndExit()

wls/env/destroy-work-manager.py

workManagerPath='/SelfTuning/%s/WorkManagers/%s' %(deployed.container.domain.name, deployed.name)
connectAndEdit()

if not exists(workManagerPath):
    print "Work manager with name %s does not exist." %(deployed.name)
    sys.exit(1)

cd(workManagerPath)
currentTargets = get('Targets')
print 'oldTargets: %s' %(currentTargets)
containerTarget = ObjectName(deployed.container.objectName)
newTargets = []
for t in currentTargets:
    if t != containerTarget:
       newTargets.append(t)

print 'new targets: %s' %(newTargets)
if len(newTargets) > 0:
       print 'Modifying work manager %s' %(deployed.name)
       set('Targets', jarray.array(newTargets, ObjectName))
else:
       print 'Deleting workmanager %s' % (deployed.name)
       cd('../')
       delete(deployed.name, 'WorkManagers')


saveAndExit()

Note 1: In the above example Python files, functions 'connectAndEdit()', 'saveAndExit()' are utility functions defined in the base.py file in WLS plugin. Have a look at the base.py file to see other utility functions.

Discovery

Once the admin server's Host and Domain are specified, the following containers can be discovered by the WLS plugin:

• Cluster
• Server
• JMSServer

Here is an example CLI script which discovers a sample WLS domain:

adminServerHost = repository.create(factory.configurationItem('Infrastructure/adminServerHost','overthere.SshHost', 
            {'os':'UNIX','connectionType':'SFTP', 'address':'wls-103', 'username':'demo-user', 'password':'demo-password'}))

wlsDomain = factory.configurationItem('Infrastructure/demoWlsDomain', 'wls.Domain', 
              {'wlHome':'/opt/bea-10.3/wlserver_10.3', 'domainHome':'/opt/bea-10.3/user_projects/domains/demoWlsDomain', 
              'port':'7001', 'username':'weblogic', 'password':'weblogic', 'adminServerName':'adminServer', 
              'startMode':'NodeManager', 'host':'Infrastructure/adminServerHost'})

discoveredItems = deployit.discover(wlsDomain)
print discoveredItems

#discovery just discovers the topology and keeps the configuration items in memory. Save them in Deployit repository
repository.create(discoveredItems)

Limitations

• The WLS topology discovery doesn't discover/associate the Host associated with the managed Servers. So if a Cluster is spanned on multiple Hosts, the creation of the managed server's Host and it's association with the Server is a manual process. This can be done using the CLI or more easily, using the UI. This may be needed for certain deployment scenarios where knowledge of the Server's Host is needed (like NoStage deployments) .