com.novell.zos.jdl
Class MatrixInfo

java.lang.Object
  com.novell.zos.jdl.GridObjectInfo
      com.novell.zos.jdl.MatrixInfo

public class MatrixInfo
extends GridObjectInfo

The MatrixInfo class is a representation of the matrix grid object.
This provides operations for retrieving and creating grid objects in the system. MatrixInfo is retrieved using the built-in getMatrix() function. Write capability is dependent on the context in which getMatrix() is called. For example, in a Joblet process on a resource or in a Computed Fact, creating new grid objects is not supported.

Method Summary

GridObjectInfo	createGridObject(java.lang.String objectType, java.lang.String objectName) Create a Grid Object using supplied type and name.
GroupInfo	createGroup(java.lang.String gridObjectType, java.lang.String groupName) Create and return a Group Grid Object using the supplied grid object type and group name.
ResourceInfo	createResource(java.lang.String name) Create a Physical Resource Grid Object with supplied name.
ResourceInfo	createResource(java.lang.String name, java.lang.String type) Create a Resource Grid Object using supplied Resource type.
ResourceInfo	createResource(java.lang.String name, java.lang.String type, boolean addSuffix) Create a Resource Grid Object using supplied Resource type.
java.lang.String	deploy(java.lang.String path) Deploy a component to this server.
void	discoverAll(java.lang.String provisioningAdapterName) Initiate a discovery of all VmHosts and Repositories under management of the supplied provisioning adapter name.
org.python.core.PyList	getActiveJobs() Retrieve a list of Job Instance Grid Objects representing the currently active job instances.
GridObjectInfo	getGridObject(java.lang.String objectType, java.lang.String objectName) Retrieve a named Grid Object of the requested type.
org.python.core.PyList	getGridObjects(java.lang.String objectType, Constraint constraint) Return a list of all matching grid objects of the requested type that match the constraints.
org.python.core.PyList	getGridObjects(java.lang.String objectType, Constraint constraint, java.lang.String[] rankBy) Return a list of all matching grid objects of the requested type that match the constraints and in the supplied order ranking.
org.python.core.PyList	getGridObjects(java.lang.String objectType, java.lang.String constraintStr) Return a list of all matching grid objects of the requested type that match the constraints.
org.python.core.PyList	getGridObjects(java.lang.String objectType, java.lang.String constraintStr, java.lang.String[] rankBy) Return a list of all matching grid objects of the requested type that match the constraints and in the supplied order ranking.
GroupInfo	getGroup(java.lang.String gridObjectType, java.lang.String groupName) Retrieve Group Grid Object supplying a grid object type and a group name.
PolicyInfo	getPolicy(java.lang.String name) Retrieve a Policy object.
java.lang.String	getTempDir() Retrieve the system temporary directory to use for creating temporary files.
boolean	match(MatchContext mc, Constraint constraint) Evaluate a given constraint using a supplied MatchContext.
boolean	match(MatchContext mc, java.lang.String constraintType) Evaluate a given constraint type using a supplied MatchContext.
MatchResult	matchAll(MatchContext mc, Constraint constraint) Evaluate a given constraint using a supplied MatchContext.
MatchResult	matchAll(MatchContext mc, java.lang.String constraintType) Evaluate a given constraint type using a supplied MatchContext.
MatchResult	matchFirst(MatchContext mc, Constraint constraint) Evaluate a given constraint using a supplied MatchContext.
MatchResult	matchFirst(MatchContext mc, java.lang.String constraintType) Evaluate a given constraint type using a supplied MatchContext.
void	removeGridObject(java.lang.String objectType, java.lang.String objectName) Remove a Grid Object from the system using supplied type and name.
void	removeGroup(java.lang.String gridObjectType, java.lang.String groupName) Remove Group Grid Object supplying a grid object type and a group name.
void	undeploy(java.lang.String component) Undeploy a component from this server.

Methods inherited from class com.novell.zos.jdl.GridObjectInfo

deleteFact, factExists, getFact, getFact, getFactLastModified, getFactNames, refresh, setArrayFact, setBooleanArrayFact, setDateArrayFact, setDateFact, setFact, setIntegerArrayFact, setRealArrayFact, setStringArrayFact, setTimeArrayFact, setTimeFact

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

createResource

public ResourceInfo createResource(java.lang.String name)

Create a Physical Resource Grid Object with supplied name.

Parameters:

name - Name of new Resource Grid Object

Returns:

New Resource Grid Object

Throws:

java.lang.Exception - if resource already exists

createResource

public ResourceInfo createResource(java.lang.String name,
                                   java.lang.String type)

Create a Resource Grid Object using supplied Resource type.

The Resource type must be one of the constants from ResourceInfo. ResourceInfo.TYPE_FIXED,ResourceInfo.TYPE_VM_INSTANCE,ResourceInfo.TYPE_VM_TEMPLATE

Parameters:

name - Name of new Resource Grid Object

type - One of the Resource types.

Returns:

New Resource Grid Object

Throws:

java.lang.Exception - if resource already exists

createResource

public ResourceInfo createResource(java.lang.String name,
                                   java.lang.String type,
                                   boolean addSuffix)

Create a Resource Grid Object using supplied Resource type.

The Resource type must be one of the constants from ResourceInfo. ResourceInfo.TYPE_FIXED,ResourceInfo.TYPE_VM_INSTANCE,ResourceInfo.TYPE_VM_TEMPLATE

Parameters:

name - Name of new Resource Grid Object

type - One of the Resource types.

addSuffix - true to make the name unique by automatically adding a numeric suffix

Returns:

New Resource Grid Object

Throws:

java.lang.Exception - if resource already exists

createGroup

public GroupInfo createGroup(java.lang.String gridObjectType,
                             java.lang.String groupName)

Create and return a Group Grid Object using the supplied grid object type and group name. The grid object type must be one of the known types and the group must not already exist.

Built-in "object type" variable constants:

      TYPE_USER
      TYPE_JOB
      TYPE_RESOURCE
      TYPE_REPOSITORY
 

Parameters:

gridObjectType - One of the known grid object types

groupName - Name of group to retrieve. It must not exist.

Returns:

Group Grid Object that was created

Throws:

exception - if group already exists

removeGroup

public void removeGroup(java.lang.String gridObjectType,
                        java.lang.String groupName)

Remove Group Grid Object supplying a grid object type and a group name. The grid object type must be one of the known types and the group must exist.

Parameters:

gridObjectType - One of the known grid object types

groupName - Name of group to retrieve. It must exist.

Throws:

exception - if group does not exist

getGroup

public GroupInfo getGroup(java.lang.String gridObjectType,
                          java.lang.String groupName)

Retrieve Group Grid Object supplying a grid object type and a group name. The grid object type must be one of the known types. None is returned if the group does not exist.

Built-in "object type" variable constants:

      TYPE_USER
      TYPE_JOB
      TYPE_RESOURCE
      TYPE_REPOSITORY
 

Parameters:

gridObjectType - One of the known grid object types

groupName - Name of group to retrieve. It must exist.

Returns:

Group Grid Object requested or None if group does not existw

Throws:

java.lang.Exception - if grid object type is invalid

getPolicy

public PolicyInfo getPolicy(java.lang.String name)

Retrieve a Policy object. The returned Policy object allows fact and policy association operations.

Parameters:

name - Name of policy. Policy must exist

Returns:

Policy Grid Object

Throws:

exception - if policy does not exist

createGridObject

public GridObjectInfo createGridObject(java.lang.String objectType,
                                       java.lang.String objectName)

Create a Grid Object using supplied type and name.

Built-in "object type" variable constants:

      TYPE_USER
      TYPE_RESOURCE
      TYPE_REPOSITORY
 

Creating an object of TYPE_RESOURCE will create a physical resource. Use createResource to supply a resource type (such as VM, VM Template). Job, Job Instance and Policy objects cannot be created this way. Jobs and policies are deployed and Job Instance objects are created as a result of starting a job.

Parameters:

objectType - Grid Object type

objectName - Grid Object name

Returns:

GridObjectInfo for new object

Throws:

java.lang.Exception - if object already exists

removeGridObject

public void removeGridObject(java.lang.String objectType,
                             java.lang.String objectName)

Remove a Grid Object from the system using supplied type and name.

Parameters:

objectType - Grid Object type

objectName - Grid Object name

Throws:

java.lang.Exception - if object does not exist

getGridObject

public GridObjectInfo getGridObject(java.lang.String objectType,
                                    java.lang.String objectName)

Retrieve a named Grid Object of the requested type.

Example to retrieve the Grid Object for the user named 'foo' and print the value of the user object's id fact:

      gridObject = getMatrix().getGridObject(TYPE_USER,"foo")
      print gridObject.getFact("user.id")
 

Built-in "object type" variable constants:

      TYPE_USER
      TYPE_JOB
      TYPE_JOBINSTANCE
      TYPE_RESOURCE
      TYPE_VMHOST
      TYPE_VMHOSTCLUSTER
      TYPE_REPOSITORY
      TYPE_USERGROUP
      TYPE_JOBGROUP
      TYPE_RESOURCEGROUP
      TYPE_REPOSITORYGROUP
 

Parameters:

objectType - Grid Object type

objectName - Grid Object name

Returns:

GridObjectInfo representing the Grid Object or None if object does not exist

Throws:

java.lang.Exception - if supplied object type is invalid

getGridObjects

public org.python.core.PyList getGridObjects(java.lang.String objectType,
                                             java.lang.String constraintStr)

Return a list of all matching grid objects of the requested type that match the constraints.

The constraint is expected to only contain facts that relate to the object being searched. Other supplied constraints (if otherwise valid) will always evaluate to false and thus will always result in no matches.

Parameters:

objectType - the Grid Object type to search for

constraintStr - the string representation of the constraint to be used in the search.

Throws:

GridAuthenticationException - is the supplied credentials are invalid or do no permit the operation.

GridException - if any error occurs such as an illegal constraint

getGridObjects

public org.python.core.PyList getGridObjects(java.lang.String objectType,
                                             java.lang.String constraintStr,
                                             java.lang.String[] rankBy)

Return a list of all matching grid objects of the requested type that match the constraints and in the supplied order ranking.

The constraint is expected to only contain facts that relate to the object being searched. Other supplied constraints (if otherwise valid) will always evaluate to false and thus will always result in no matches.

Ordering is specified as an array of strings with each element in the form '<factname>/<ascending|descending>'. The ascending/decending order may be shortened to 'a|d'.

Parameters:

objectType - the Grid Object type to search for

constraintStr - the string representation of the constraint to be used in the search.

rankBy - the specification used to order the returned array or None for don't care

Throws:

GridAuthenticationException - is the supplied credentials are invalid or do no permit the operation.

GridException - if any error occurs such as an illegal constraint

getGridObjects

public org.python.core.PyList getGridObjects(java.lang.String objectType,
                                             Constraint constraint)

Return a list of all matching grid objects of the requested type that match the constraints. The constraint is expected to only contain facts that relate to the object being searched. Other supplied constraints (if otherwise valid) will always evaluate to false and thus will always result in no matches.

Example to get all resources running on a specific operating system:

      constraint = EqConstraint()
      constraint.setFact("resource.os.name")
      constraint.setValue("Windows XP")
      resources = getMatrix().getGridObjects(TYPE_RESOURCE, constraint)
 

Parameters:

constraint - the constraint to be used in the search.

objectType - the Grid Object type to search for

Returns:

An array of all matching grid objects or null if none match

Throws:

GridAuthenticationException - is the supplied credentials are invalid or do no permit the operation.

GridException - if any error occurs such as an illegal constraint

getGridObjects

public org.python.core.PyList getGridObjects(java.lang.String objectType,
                                             Constraint constraint,
                                             java.lang.String[] rankBy)

Return a list of all matching grid objects of the requested type that match the constraints and in the supplied order ranking. The constraint is expected to only contain facts that relate to the object being searched. Other supplied constraints (if otherwise valid) will always evaluate to false and thus will always result in no matches.

Ordering is specified as an array of strings with each element in the form "<factname>/<ascending|descending". The ascending/decending order may be shortened to 'a|d'.

Parameters:

constraint - the constraint to be used in the search.

objectType - the Grid Object type to search for

rankBy - the specification used to order the returned array or None for don't care

Returns:

An array of all matching grid objects or null if none match

Throws:

GridAuthenticationException - is the supplied credentials are invalid or do no permit the operation.

GridException - if any error occurs such as an illegal constraint

discoverAll

public void discoverAll(java.lang.String provisioningAdapterName)

Initiate a discovery of all VmHosts and Repositories under management of the supplied provisioning adapter name.

Parameters:

provisioningAdapterName - the name of the provisioning adapter to use for discovery.

Throws:

java.lang.Exception - if an error occurs launching or running the provisioning adpater or a discovery is already in progres.

getActiveJobs

public org.python.core.PyList getActiveJobs()

Retrieve a list of Job Instance Grid Objects representing the currently active job instances. This includes job instances that are queued.

Returns:

List of job instance Grid Objects, list will be empty if no jobs are active

deploy

public java.lang.String deploy(java.lang.String path)

Deploy a component to this server. This is not supported when invoked from within a Joblet class.

Parameters:

path - Path to a deployable file of deployables

Returns:

Deployment session identifier to use in undeployment

undeploy

public void undeploy(java.lang.String component)

Undeploy a component from this server. This is not supported when invoked from within a Joblet class.

Parameters:

component - Deployment session identifier

getTempDir

public java.lang.String getTempDir()

Retrieve the system temporary directory to use for creating temporary files. The server does not provide any automatic cleanup.

Returns:

Temp directory

match

public boolean match(MatchContext mc,
                     java.lang.String constraintType)

Evaluate a given constraint type using a supplied MatchContext.
Returns a MatchResult object which contains a set of Matching and Non-Matching Ids and reasons for failure in case of Non-matching ids.

Parameters:

mc - MatchContext for constraint evaluation

constraintType - Identify which constraint type to use for this evaluation

Returns:

MatchContext instance containing results

Throws:

java.lang.Exception - if error in supplied MatchContext or constraint

match

public boolean match(MatchContext mc,
                     Constraint constraint)

Evaluate a given constraint using a supplied MatchContext.

Parameters:

mc - MatchContext for constraint evaluation

constraint - Constraint instance to use for this evaluation

Returns:

True if any of the Ids match, False if no matches

Throws:

java.lang.Exception - if error in supplied MatchContext or constraint

matchFirst

public MatchResult matchFirst(MatchContext mc,
                              java.lang.String constraintType)

Evaluate a given constraint type using a supplied MatchContext.

Parameters:

mc - MatchContext for constraint evaluation

constraintType - Identify which constraint type to use for this evaluation

Returns:

True if any of the Ids match, False if no matches

Throws:

java.lang.Exception - if error in supplied MatchContext or constraint

matchFirst

public MatchResult matchFirst(MatchContext mc,
                              Constraint constraint)

Evaluate a given constraint using a supplied MatchContext.
Returns a MatchResult object which contains a set of Matching and Non-Matching Ids and reasons for failure in case of Non-matching ids.

Parameters:

mc - MatchContext for constraint evaluation

constraint - Constraint instance to use for this evaluation

Returns:

MatchContext instance containing results

Throws:

java.lang.Exception - if error in supplied MatchContext or constraint

matchAll

public MatchResult matchAll(MatchContext mc,
                            java.lang.String constraintType)

Evaluate a given constraint type using a supplied MatchContext.
This is more powerful than getGridObjects() in that the MatchContext can contain other objects such as the User/VmHost/Repository so that those objects can be referenced in constraints.
Returns a MatchResult object which contains a set of Matching and Non-Matching Ids and reasons for failure in case of Non-matching ids.

Parameters:

mc - MatchContext for constraint evaluation

constraintType - Identify which constraint type to use for this evaluation

Returns:

MatchContext instance containing results

Throws:

java.lang.Exception - if error in supplied MatchContext or constraint

matchAll

public MatchResult matchAll(MatchContext mc,
                            Constraint constraint)

Evaluate a given constraint using a supplied MatchContext.
This is more powerful than getGridObjects() in that the MatchContext can contain other objects such as the User/VmHost/Repository so that those objects can be referenced in constraints.
Returns a MatchResult object which contains a set of Matching and Non-Matching Ids and reasons for failure in case of Non-matching ids.
Example to evualate all resources to find ones whose ID starts with a string:

      mc = MatchContext()
      eq = EqConstraint()
      eq.setFact("resource.id")
      eq.setValue("accounting*")
      eq.setMatchMode(EqConstraint.MATCH_MODE_GLOB)
      mc.setMatchIterator(TYPE_RESOURCE)
      matchresult = getMatrix().matchAll(mc,eq)
      print "getMatchObjects()=",matchresult.getMatchObjects()
 

Parameters:

mc - MatchContext for constraint evaluation

constraint - Additional constraint for evaluation

Returns:

MatchContext instance containing results

Throws:

java.lang.Exception - if error in supplied MatchContext or constraint