IBM WebSphere Application ServerTM
Release 7

com.ibm.wbiserver.brules.mgmt
Interface BusinessRuleGroup

All Superinterfaces:
BusinessRuleChangeDetector, BusinessRuleValidateable, java.io.Serializable

public interface BusinessRuleGroup
extends BusinessRuleValidateable, BusinessRuleChangeDetector, java.io.Serializable

An object implementing this interface represents one business rule group component in the server. It is used as the starting point for accessing information related to all operations, rule sets, and decision tables that are associated with the business rule group.

A business rule group has a set of operations associated with it. These operations can be retrieved using the getOperations method. The Operation objects returned can be used to navigate to down to the rulesets and decision tables that implement the operations.

A business rule group also has a set of properties associated with it. A property is a name-value pair that is intended to give additional information about the business rule group. There are two types of properties: user-defined and system-defined. User-defined properties are completely defined and under the control of the user. They can be defined, their values can be changed, and they can be removed. System-defined properties are defined by the system and cannot be changed by the user. Properties can be used in queries to find business rule groups whose properties match certain criteria. Refer to the classes in the com.ibm.wbiserver.brules.mgmt.query package for more information about queries.

Methods are provided on the BusinessRuleManager class to query for business rule groups based on the values assigned to the properties. Once you have a business rule group you can get a list of its properties. This list includes both system-defined and user-defined properties. System-defined properties are read-only. For user-defined properties, you are also allowed to change the values of existing properties, remove existing properties, and add new properties. No validation is performed on the changes for user-defined properties since the properties and their values are completely defined by the user.

Some data on the business rule group and its sub-objects is allowed to be changed. Many changes are validated at the time the set method is called, however some changes cannot be validated at that time. Therefore a validate method is provided that can be called to perform a complete validation after all changes are made. The validate method will validate the object on which it is called and also all of its sub-objects. Changes will also be validated at the time that they are published.

The user should use one of the methods on the BusinessRuleManager class to get instances of the BusinessRuleGroup interface. BusinessRuleManager provides various method to either get all BusinessRuleGroup objects accessible to the server or to query on various properties of the business rule groups. For situations where a business rule group or sub-objects are of a newer version than what the runtime supports, a shell business rule group is instantiated. This situation occurs when the runtime configuration involves multiple servers in a single cell where the servers are of different runtime versions. Because a server can only support a certain amount of features or level of the business rule language, those business rule groups or sub-objects that use newer versions, will not be recognized by a management client and changes to these artifacts may remove or corrupt the new items in the objects. The shell business rule group limits what can be seen and changed in the newer business rule group version. The shell business rule group will be limited to only the name and target namespace of the business rule group as well as two properties, IBMSystemVersion and IBMSystemShell. The IBMSystemVersion property will list the version of the model that was used to create the business rule group. If it is a sub-object that is of a newer version, the version will be x.x.x signifing that it is a newer version that can not be determined as only the business rule group has a version recorded with the model. This property will not be part of the normal list of properties if the business rule group is not a shell. The existance of the IBMSystemShell property indicates the business rule group is a shel and not a regular business rule group. The isShell method can also be used to check if the business rule group is a shell. A shell business rule group is limited in function and basically read only. The getName, getTargetNameSpace, getProperties, getProperty, and getPropertyValue methods are the only methods which are supported. All other get and set methods will result in a UnsupportedOperationException exception thrown.


Field Summary
static java.lang.String COPYRIGHT
           
 
Method Summary
 java.lang.String getDescription()
          Get the description of the business rule group.
 java.lang.String getDisplayName()
          Get the display name for this business rule group.
 java.lang.String getName()
          Get the name of the business rule group.
 Operation getOperation(java.lang.String operationName)
          Get the operation with the specified name from the list of operations for this business rule group.
 java.util.List<Operation> getOperations()
          Get a list of all operations associated with this business rule group.
 PresentationTimezone getPresentationTimezone()
          Get the presentation time zone for the business rule group.
 PropertyList getProperties()
          Get the list of properties associated with this business rule group.
 Property getProperty(java.lang.String name)
          Get the property on this business rule group that has the specified name.
 java.lang.String getPropertyValue(java.lang.String name)
          Get the value of the property on this business rule group that has the specified name.
 java.lang.String getRuntimeID()
          Returns a globally unique ID for the business rule group.
 java.util.Date getSaveDate()
          Get the date and time that the information in this copy of the business rule group was saved to persistent storage.
 java.lang.String getTargetNameSpace()
          Get the target name space of the business rule group.
 boolean isDisplayNameSynchronizedToName()
          Check to see if the display name is synchronized to the name for this business rule group.
 boolean isGoverned()
          Returns a boolean that indicates whether the business rule group is under governance.
 boolean isShell()
          Retrieve flag indicating if a business rule group is a shell which is an indication that it is of a newer version than what is supported on the server on which it was retrieved.
 BusinessRuleGroup refresh()
          Retrieve this business rule group and its associated objects from persistent storage again.
 void setDescription(java.lang.String newDescription)
          Set the description associated with this business rule group.
 void setDisplayName(java.lang.String newDisplayName)
          Set the display name for this business rule group.
 void setDisplayNameIsSynchronizedToName(boolean newDisplayNameIsSynchronizedToName)
          Change the value of the flag that determines whether or not the display name is synchronized to the name for this business rule group.
 void setGovernance(boolean governanceEnabled)
          Set the governance value for the business rule group.
 void setPropertyValue(java.lang.String name, java.lang.String value)
          Set the value of the property with the specified name to the specified value.
 
Methods inherited from interface com.ibm.wbiserver.brules.mgmt.BusinessRuleValidateable
validate
 
Methods inherited from interface com.ibm.wbiserver.brules.mgmt.BusinessRuleChangeDetector
hasChanges
 

Field Detail

COPYRIGHT

static final java.lang.String COPYRIGHT
See Also:
Constant Field Values
Method Detail

getTargetNameSpace

java.lang.String getTargetNameSpace()
Get the target name space of the business rule group.

Returns:
The target name space of the business rule group.

getName

java.lang.String getName()
Get the name of the business rule group.

Returns:
The name of the business rule group.

getDisplayName

java.lang.String getDisplayName()
Get the display name for this business rule group. The display name may have been specified during development of the business rule group to give a name that is more understandable to the business user. A flag can be set on the business rule group to ensure that the display name value is always synchronized to the name value. If this flag is turned on, then the display name cannot be changed. See isDisplayNameSynchronizedToName and setDisplayName for more information.

Returns:
the display name of this business rule group. May be null.
Throws:
java.lang.UnsupportedOperationException - if the business rule group is a shell.

setDisplayName

void setDisplayName(java.lang.String newDisplayName)
Set the display name for this business rule group. If the display name is synchronized to the name for this business rule group (see isDisplayNameSynchronizedToName), then changes to the display name are not allowed. This is because the name field takes precedence over the display name and the name field cannot be changed. In this case a DisplayNameNotChangeableException is thrown. The list of properties for this business rule group will also be updated with the new display name value.

Parameters:
newDisplayName - The new display name for this business rule group. May be null.
Throws:
DisplayNameNotChangeableException - if the display name for this business rule group is synchronized to the name.
ChangesNotAllowedException - if changes to this object are temporarily disallowed while other changes are being published.
java.lang.UnsupportedOperationException - if the business rule group is a shell.

isDisplayNameSynchronizedToName

boolean isDisplayNameSynchronizedToName()
Check to see if the display name is synchronized to the name for this business rule group. Synchronizing the display name to the name means that the display name value will always be the same as the name value. One consequence of this is that since the name is not changeable, when the two are synchronized you are not allowed to change the display name either. If the display name is not synchronized to the name, then the display name can be changed.

Returns:
true if the display name is synchronized to the name for this business rule group; otherwise false.
Throws:
java.lang.UnsupportedOperationException - if the business rule group is a shell.

setDisplayNameIsSynchronizedToName

void setDisplayNameIsSynchronizedToName(boolean newDisplayNameIsSynchronizedToName)
Change the value of the flag that determines whether or not the display name is synchronized to the name for this business rule group. Synchronizing the display name to the name means that the display name value will always be the same as the name value. One consequence of this is that since the name is not changeable, when the two are synchronized you are not allowed to change the display name either. If the display name is not synchronized to the name, then the display name can be changed.

When this method is called with a value of true, the display name is automatically changed to have the same value as the name.

Parameters:
newDisplayNameIsSynchronizedToName - The new value for the flag that determines whether or not the display name is synchronized to the name for this business rule group.
Throws:
ChangesNotAllowedException - if changes to this object are temporarily disallowed while other changes are being published.
java.lang.UnsupportedOperationException - if the business rule group is a shell.

getDescription

java.lang.String getDescription()
Get the description of the business rule group.

Returns:
The description of the business rule group.
Throws:
java.lang.UnsupportedOperationException - if the business rule group is a shell

setDescription

void setDescription(java.lang.String newDescription)
Set the description associated with this business rule group.

Parameters:
newDescription - The new description to be associated with this business rule group. May be null.
Throws:
ChangesNotAllowedException - if changes to this object are temporarily disallowed while other changes are being published.
java.lang.UnsupportedOperationException - if the business rule group is a shell.

getPresentationTimezone

PresentationTimezone getPresentationTimezone()
Get the presentation time zone for the business rule group. This value indicates the time zone in which dates and times associated with this business rule group should be displayed to the user.

Returns:
The presentation time zone for the business rule group.
Throws:
java.lang.UnsupportedOperationException - if the business rule group is a shell.

getOperations

java.util.List<Operation> getOperations()
Get a list of all operations associated with this business rule group. Each Operation object returned represents one operation that can be invoked on this business rule group component.

Returns:
A List of Operation objects. The returned List is unmodifiable.
Throws:
java.lang.UnsupportedOperationException - if the business rule group is a shell.
See Also:
Operation

getOperation

Operation getOperation(java.lang.String operationName)
Get the operation with the specified name from the list of operations for this business rule group. If there is no operation with the specified name associated with this business rule group, then null is returned.

Parameters:
operationName - The name of the operation to return. Must not be null.
Returns:
The Operation object associated with this BusinessRuleGroup that has the specified name or null if there is no such Operation.
Throws:
java.lang.IllegalArgumentException - if the specified name is null.
java.lang.UnsupportedOperationException - if the business rule group is a shell.

getProperties

PropertyList getProperties()
Get the list of properties associated with this business rule group. This list includes both system-defined and user-defined properties. If this business rule group has no properties, then the PropertyList returned is empty. For a shell business business rule group, the only two properties that will be returned are PROPERTY_NAME__VERSION and PROPERTY_NAME__SHELL.

Returns:
The list of properties associated with this business rule group.

getPropertyValue

java.lang.String getPropertyValue(java.lang.String name)
Get the value of the property on this business rule group that has the specified name. Returns null if there is no property with that name. For a shell business business rule group, the only two property values that can be retrieved are PROPERTY_NAME__VERSION and PROPERTY_NAME__SHELL.

Parameters:
name - The name of the property whose value is to be returned. Must not be null.
Returns:
The value of the property on this business rule group that has the specified name. Returns null if there is no property with that name.
Throws:
java.lang.IllegalArgumentException - if the name parameter is null.

getProperty

Property getProperty(java.lang.String name)
Get the property on this business rule group that has the specified name. Returns null if there is no property with that name. For a shell business business rule group, the only two properties that can be retrieved are PROPERTY_NAME__VERSION and PROPERTY_NAME__SHELL.

Parameters:
name - The name of the property to be retrieved. Must not be null.
Returns:
The property on this business rule group that has the specified name. Returns null if there is no property with that name.
Throws:
java.lang.IllegalArgumentException - if the name parameter is null.

setPropertyValue

void setPropertyValue(java.lang.String name,
                      java.lang.String value)
Set the value of the property with the specified name to the specified value. If a property with the specified name already exists, then its value is changed to the specified value. If no property exists with the specified name, then a new property is defined with the specified name and value. If the specified value is null and the property is currently defined, then the property will be removed from this business rule group. If the specified value is null and the property is not currently defined, then no action is taken.

Only user-defined properties are changeable. If a property with the specified name does not already exist, the new property created will be user-defined. If a system-defined property with the specified name already exists for this business rule group, then a SystemPropertyNotChangeableException will be thrown.

Parameters:
name - The name of the property whose value is to be set. Must not be null or the zero-length string.
value - The value that the property should be set to. May be null.
Throws:
java.lang.IllegalArgumentException - if the name parameter is null or is the zero-length string.
SystemPropertyNotChangeableException - if a property with the specified name already exists for this business rule group and it is system-defined.
java.lang.UnsupportedOperationException - if the business rule group is a shell.

getSaveDate

java.util.Date getSaveDate()
Get the date and time that the information in this copy of the business rule group was saved to persistent storage. This date and time is stored in persistent storage along with the business rule group. When a BusinessRuleGroup is retrieved using one of the methods on the BusinessRuleManager class, its save date is retrieved from persistent storage as well and is stored in the in-memory BusinessRuleGroup object. It is important to remember that this is a copy of the save date at the point in time at which the BusinessRuleGroup was retrieved. If another user changes the business rule group in persistent storage, the save date in persistent storage will now be different than the date in your in-memory copy. The next time the BusinessRuleGroup is retrieved, the save date in the new in-memory copy will be different.

The save date of a business rule group in persistent storage is only changed when a change is published using the BusinessRuleManager publish method or when some other operation (such as installing a new version of the application) updates the business rule group in persistent storage. The in-memory copy of the save date is updated when a publish is performed using that BusinessRuleGroup object.

When a BusinessRuleGroup is published, if the save date in persistent storage is different from the save date in the in-memory object that is being published, then the publish will fail with a ChangeConflictException. This is because publishing the current changes would overwrite changes that were made by some other user. When you get a ChangeConflictException, if you still want to publish the current changes, you must retrieve the business rule group again and merge the current changes into the new BusinessRuleGroup.

Returns:
the date and time that the information in this copy of the business rule group was saved to persistent storage.
Throws:
java.lang.UnsupportedOperationException - if the business rule group is a shell.

refresh

BusinessRuleGroup refresh()
                          throws BusinessRuleManagementException
Retrieve this business rule group and its associated objects from persistent storage again. A new BusinessRuleGroup object is returned containing the current data from persistent storage. The BusinessRuleGroup object on which this method was called, as well as any of its sub-objects, should now be considered obsolete. They contain old data.

it is possible that the business rule group has been deleted from persistent storage since it was originally retrieved. If this is the case, then this method will return null.

Returns:
A new BusinessRuleGroup object containing the current data from persistent storage. May be null if the business rule group has been deleted from persistent storage.
Throws:
java.lang.UnsupportedOperationException - if the business rule group is a shell.
BusinessRuleManagementException

isShell

boolean isShell()
Retrieve flag indicating if a business rule group is a shell which is an indication that it is of a newer version than what is supported on the server on which it was retrieved.

Returns:
indication on whether the business rule group is a shell or a regular business rule group

getRuntimeID

java.lang.String getRuntimeID()
Returns a globally unique ID for the business rule group. The ID value is set on installation. The ID remains the same between retrievals and publishes. If an artifact was installed in a previous application version, it will be updated and a new ID value will be created.

Returns:
a globally unique ID

isGoverned

boolean isGoverned()
Returns a boolean that indicates whether the business rule group is under governance. The implication with a value of true is that when the business rule group is published whether it will go through an approval process. This value will always return false for business rule groups that are part of applications that are were created prior to v6.2.

Returns:
boolean

setGovernance

void setGovernance(boolean governanceEnabled)
Set the governance value for the business rule group. When the value is true this will force the business rule group to go through an approval process. When the value is false, the business rule group will not go through an approval process on publish. This value can only be called if changed by an individual with Owner permission to the business rule group. This method has no affect on business rule groups that are part of applications that are were created prior to v6.2.

Parameters:
boolean - indication on governance support

IBM WebSphere Application ServerTM
Release 7