4. Resources and Groups

4.1. Creating and Updating Content-Backed Resources (Web Apps)

Web applications (EARs and WARs) are content-backed resources, a cross between a managed resource and a content package.
When running a CLI script, there are some methods available specifically to retrieve or create the content for the resource.
To create a content-backed resource, upload the file with a specified version number.
This script's steps are:
  1. Search for the resource to upload the content to. This example looks for a JBoss AS 5 server.
  2. Make sure the server is running. The JBoss server has to be running for content to be deployed successfully.

Example 5. Creating a Content-Backed Resource

// fill this information in before running the script
var pathName = '/home/jon/myExampleApp.ear'

var resTypeName = 'JBossAS Server'
var pluginName = "JBossAS5"
var appTypeName = "Enterprise Application (EAR)"

// define a custom function to parse the filename and path info
function PackageParser(pathName) {
    var file = new java.io.File(pathName);
    var fileName = file.getName();
    var packageType = fileName.substring(fileName.lastIndexOf('.')+1);
    var tmp = fileName.substring(0, fileName.lastIndexOf('.'));
    var version = 1;
    var realName = tmp;
    var packageName = fileName;
    
    // parse the package version, only if version is included   
    if(tmp.indexOf('-') != -1){
	realName = tmp.substring(0, tmp.lastIndexOf('-'));
	version = tmp.substring(tmp.lastIndexOf('-') + 1);			
        packageName = realName + "." + packageType;
    }	
	
    this.packageType = packageType.toLowerCase();
    this.packageName = packageName;
    this.version     = version;
    this.realName    = realName;
    this.fileName    = fileName;
}

criteria = new ResourceCriteria();
criteria.addFilterResourceTypeName(resTypeName);
criteria.addFilterPluginName(pluginName);
var resources = ResourceManager.findResourcesByCriteria(criteria);

// create the config options for the new EAR 
var deployConfig = new Configuration();
deployConfig.put( new PropertySimple("deployExploded", "false"));
deployConfig.put( new PropertySimple("deployFarmed", "false"));
 

// stream in the file bytes
var file = new java.io.File(pathName);
var inputStream = new java.io.FileInputStream(file);
var fileLength = file.length();
var fileBytes = java.lang.reflect.Array.newInstance(java.lang.Byte.TYPE, fileLength);
for (numRead=0, offset=0; ((numRead >= 0) && (offset < fileBytes.length)); offset += numRead ) {
    numRead = inputStream.read(fileBytes, offset, fileBytes.length - offset); 	
}

// parse the filename and path info
PackageParser(pathName);

// identifies the type of resource being created
var appType = ResourceTypeManager.getResourceTypeByNameAndPlugin(appTypeName, pluginName);

// create the new EAR resource on each discovered app server
if( resources != null ) {
  for( i =0; i < resources.size(); ++i) {
       var res = resources.get(i);println("res: " + res);
       ResourceFactoryManager.createPackageBackedResource(
           res.id,
           appType.id, 
           packageName,
           null,  // pluginConfiguration
           packageName,
           version,
           null, // architectureId        
           deployConfig,
           fileBytes,
           null // timeout
       );
  }
}
Updating a package is slightly simpler. It requires sending a new file and version number to the existing EAR resource.

Example 6. Updating a Content-Backed Resource

// update this
var fullPathName = '/export/myfiles/updatedApp.ear'

// define a custom function to parse the filename and path info
function PackageParser(pathName) {
    var file = new java.io.File(pathName);
		
    var fileName = file.getName();
    var packageType = fileName.substring(fileName.lastIndexOf('.')+1);
    var tmp = fileName.substring(0, fileName.lastIndexOf('.'));
    var version = 1;
    var realName = tmp;
    var packageName = fileName;
    
    // parse the package version, only if version is included   
    if(tmp.indexOf('-') != -1){
        realName = tmp.substring(0, tmp.lastIndexOf('-'));
        version = tmp.substring(tmp.lastIndexOf('-') + 1);			
        packageName = realName + "." + packageType;
    }	
	
    this.packageType = packageType.toLowerCase();
    this.packageName = packageName;
    this.version     = version;
    this.realName    = realName;
    this.fileName    = fileName;
}

// parse the filename and path info
PackageParser(fullPathName);
                
// search for the JBoss AS 5 server by name
criteria = new ResourceCriteria();
criteria.addFilterName('My JBoss AS 5 Server');
var res = ResourceManager.findResourcesByCriteria(criteria);

var jboss = ProxyFactory.getResource(res.get(0).id);

var children = jboss.children;
for( c in children ) {
    var child = children[c];
    if( child.name == packageName ) {
        child.updateBackingContent(fullPathName,version);
    }
}
While a content-backed resource is added or updated as if it were a software package (which it is), it is deleted as if it were a resource.

Note

Deleting is not the same as uninventorying a resource. Uninventorying removes the resource from the inventory but leaves it intact on the platform. Deleting a resource deletes it from the platform itself.

Example 7. Deleting a Content-Backed Resource

// search for the content resource by name
criteria = new ResourceCriteria();
criteria.addFilterName('updatedApp.ear');
var res = ResourceManager.findResourcesByCriteria(criteria);

ResourceFactoryManager.deleteResource(res.get(0).id)

4.2. Creating a Resource Group and Adding Members

When a group is created by a script, it is initially created as a mixed group. All empty groups are treated as mixed groups. Once members are added, if all the members are the same resource type, then the group is automatically tagged as a compatible group.
Compatible groups are great for scripted management tasks, because the same operation or configuration change can be performed on each member iteratively.
The script steps are:
  1. Search for the resource type.
  2. Create the group, based on the resource type.
  3. Find resources of that resource type.
  4. Iterate through the returned resources and add them to the group.

Example 8. Annotated Example

// search for the resource type to use for the compat group
var resType = ResourceTypeManager.getResourceTypeByNameAndPlugin("Linux","Platforms");

//create the new resource group
var rg = new ResourceGroup(resType);
rg.setRecursive(false);
rg.setName('Linux Group - ' + java.util.Date());

rg = ResourceGroupManager.createResourceGroup(rg);

//find resources to add to the group based on their resource type
criteria = new ResourceCriteria();
criteria.addFilterResourceTypeId(resType.id);

var resources = ResourceManager.findResourcesByCriteria(criteria);

// add the found resources to the group
if( resources != null ) {
  for( i =0; i < resources.size(); ++i) {
       var resource = resources.get(i);
       ResourceGroupManager.addResourcesToGroup(rg.id, [resource.id]);
  }
}

4.3. Creating and Editing Dynagroups

A dynamic groups specifies a search term to use to search the inventory and identify matching resources to belong to the group. Since the search results change automatically as results are added and removed from the inventory, the group membership is always changing and always current.
Dynamic groups (or dynagroups) have their own classes to create and update groups.
A dynagroup is created by defining a set of expressions which are search filters to use to search the inventory for matching members. The group membership is calculated (using those expressions) by an administrative task.

Note

Dynagroups expressions are covered extensively in the Users Guide.
Both for creating an editing a dynagroup, then, it is necessary to recalculate the group membership to capture changes to matching members. It can also be reasonable to recaculate group membership whenever there are changes to the inventory, to update the dynagroups with new members.

Example 9. Creating a Dynagroup

This uses simple expressions to identify group members. 
// create the new dynagroup
var dynaGroupDef = new GroupDefinition("Linux Group");
var expr = "resource.type.name=Linux" + "\n" + "resource.type.category=Platform"
dynaGroupDef.setExpression(expr);
var def = GroupDefinitionManager.createGroupDefinition(dynaGroupDef);

// calculate the group members
GroupDefinitionManager.calculateGroupMembership(def.getId());
It is possible to use more complex expressions such as groupby within the setExpression value.

Example 10. Editing a Dynagroup

This adds another expression to the dynagroup, updates the definition, and then recalculates the group membership. 
// search for the dynagroup
criteria = new ResourceGroupDefinitionCriteria()
criteria.addFilterName("All agents");
var orig = GroupDefinitionManager.findGroupDefinitionsByCriteria(criteria)

// get the dynagroup entry
var originalGroupDef = orig.get

// add the new expression
originalGroupDef.setExpression("resource.name=*.example.com");
var def = GroupDefinitionManager.updateGroupDefinition(originalGroupDef);

// calculate the group members
GroupDefinitionManager.calculateGroupMembership(def.getId());
Dynagroup memberships are only updated after a calculation operation. So, if there are changes to the inventory, even if there are not changes to the dynagroup expression itself, the dynagroup must be updated to update the members.

Example 11. Recalculating a Group Definition

This updates a single dynagroup, based on the group name. 
// search for the dynagroup
criteria = new ResourceGroupDefinitionCriteria()
criteria.addFilterName("All agents");
var orig = GroupDefinitionManager.findGroupDefinitionsByCriteria(criteria)

// calculate the group members
GroupDefinitionManager.calculateGroupMembership(orig.getId());
It is possible to recalculate all dynagroups or a set of dynagroups, by incrementing through the search results and running the calculatedGroupMembership() method. This is covered in Section 3, “Getting Data for Single and Multiple Resources”.