IBM Rational Software Modeler
Release 6.0

com.ibm.xtools.patterns.framework
Class AbstractPatternParameter

java.lang.Object
  extended bycom.ibm.xtools.patterns.framework.AbstractPatternElement
      extended bycom.ibm.xtools.patterns.framework.AbstractPatternParameter
All Implemented Interfaces:
Comparable, IParameterDescriptor, ITransformationDescriptor, ITransformationItem, Visitable
Direct Known Subclasses:
AbstractPatternParameter

public abstract class AbstractPatternParameter
extends com.ibm.xtools.patterns.framework.AbstractPatternElement
implements IParameterDescriptor, Visitable

This class is the common implementation for a pattern parameter and will typically be used indirectly through another subclass that further specializes this class. Everything that specifies a pattern parameter is encapsulated in this class. This class is abstract because it is meant to be extended with the run-time expansion methods being implemented. This class stores and manages dependencies from this parameter to another parameter. It also stores an OCL expression that can optionally be used to constrain the validity of a parameter value. The ordinal position of the parameter is also stored. By default, the order in which the parameters are instantiated determine the ordinal positions of the pattern parameters. The abstract pattern parameter is an important abstraction in the framework's design because it allows the run-time execution or expansion behavior be broken apart and encapsulated within the parameter performing the behavior. Instead of implementing all the pattern execution logic in the pattern definition or pattern instance, the responsibility for expansion is instead spread across the parameters that encapsulate how to behave appropriately. The parameter abstraction also allows concepts like parameter dependencies and parameter delegates to manifest cleanly in the design since these abstractions build on and collaborate with an abstract pattern parameter. The abstract pattern parameter also contains some member classes such as two strategies for validating pattern parameter values, a descriptor implementation for dynamically-defined patterns and an observerable adapter that allows this class to be observable even though the single superclass slot is already occupied. The strategy pattern is used for parameter value validation and the strategy is also used for descriptor-switching between statically-defined and dynamically-defined patterns (just like the abstract pattern definition class). The internal iteration idiom is used by supplying a consumer class for entities that consume abstract pattern parameters. A good amount of the differing code between patterns is on or around the abstract pattern parameter abstraction. The abstract pattern parameter is the primary abstraction at run-time forming the backbone for an expansion to take place through parameters, parameter dependencies and delegates. There are a handful of hot-spots that can be overridden within this class. It is expected that most pattern implementations will implement some or most of these hot-spots by overriding the hot-spot methods. The most frequently implemented hot-spots would be the expand and is valid methods. Hot-spot methods are available for resolving alternatively specified parameter values and determining validity of these alternatively specified parameter values.

See Also:
initialize(), expand(PatternParameterValue), expand(PatternParameterValue.Added), expand(PatternParameterValue.Maintained), expand(PatternParameterValue.Removed), isValid(PatternParameterValue.Proposed), isValid(PatternParameterValue.Unresolved), isValid(PatternParameterValue.Unresolved, PatternParameterValue.Unresolved.Directive), validToAddArgument(PatternParameterValue.Proposed), validToAddArgument(PatternParameterValue.Unresolved), validToReplaceArgument(PatternParameterValue.Proposed), validToReplaceArgument(PatternParameterValue.Unresolved), resolve(PatternParameterValue.Unresolved), resolve(PatternParameterValue.Unresolved, PatternParameterValue.Unresolved.Directive), validToCreateArguments(AbstractPatternInstance, IPatternMetatype), create(AbstractPatternInstance, IPatternMetatype), isScopeDerivable(), getDerivedScope(AbstractPatternInstance), isRetrievable(), retrieve(AbstractPatternInstance, String), isTypeSubstitutable(), getSubstituteType(), AbstractPatternDefinition

Field Summary
 
Fields inherited from interface com.ibm.xtools.patterns.core.IParameterDescriptor
BINDABLE
 
Fields inherited from interface com.ibm.xtools.transform.core.ITransformationDescriptor
AUTHOR, DESCRIPTION, DOCUMENT, EXTENSIBLE, GROUP_PATH, GROUP_PATH_DELIMITERS, ICON, ID, KEYWORDS, KEYWORDS_DELIMITERS, NAME, PROFILES, PROFILES_DELIMITERS, PROVIDER, PUBLIC, SOURCE_MODEL_TYPE, SOURCE_MODEL_TYPE_DELIMITERS, TARGET_MODEL_TYPE, TARGET_MODEL_TYPE_DELIMITERS, TRANSFORM_GUI, VERSION
 
Constructor Summary
AbstractPatternParameter(AbstractPatternDefinition owningDefinition, PatternParameterIdentity parameterIdentity)
          Constructs a pattern parameter given only the parameter identity; the parameter descriptor offered by associated static pattern provider will then be attached to this parameter as the concrete descriptor state in this class.
AbstractPatternParameter(AbstractPatternDefinition owningDefinition, PatternParameterIdentity parameterIdentity, String oclExpression)
          Constructs a patterm parameter given only the parameter identity; the parameter descriptor offered by associated static pattern provider will then be attached to this parameter as the concrete descriptor state in this class.
 
Method Summary
 void accept(Visitor visitor)
          Enable visitation of this entity.
 int compareTo(Object object)
           
protected abstract  Object[] create(AbstractPatternInstance instance, IPatternMetatype metatype)
          If this parameter supports creation of prototypical instances then this method will be implemented.
protected abstract  Object[] create(AbstractPatternInstance instance, IPatternMetatype metatype, String scopeQualifiedName)
          If this parameter supports creation of prototypical instances then this method will be implemented.
 Object[] createArgumentsUsingPairs(AbstractPatternInstance instance, IPatternMetatype metatype, AbstractParameterArgument.Pair[] pairs)
          If this parameter supports creation of prototypical instances then this method will be implemented.
 boolean equals(Object object)
           
protected  boolean expand(PatternParameterValue.Added value)
          A hot-spot method that can be overridden in parameter subclasses.
protected  boolean expand(PatternParameterValue.Maintained value)
          A hot-spot method that can be overridden in parameter subclasses.
protected  boolean expand(PatternParameterValue.Removed value)
          A hot-spot method that can be overridden in parameter subclasses.
protected  boolean expand(PatternParameterValue.Replaced value)
          A hot-spot method that can be overridden in parameter subclasses.
protected  boolean expand(PatternParameterValue value)
          A hot-spot method that can be overridden in parameter subclasses.
 IPatternMetatype[] getAlternateTypes()
          Retrieves the alternate types that are accepted for the arguments of the parameter represented by this descriptor.
protected  Object getDerivedScope(AbstractPatternInstance instance)
          Retrieves the derived scope which in turn can be used to resolve parameter values and create parameter values within.
 String getDescription()
          Retrieve the localized description of the transformation item.
 AbstractParameterArgument[] getFirstArgumentCandidates(AbstractPatternInstance instance, IPatternMetatype metatype, MultiStatus status)
           
 String getId()
          Retrieve the unique id of the transformation item.
 IMultiplicity getMultiplicity()
          Retrieves the multiplicity of the parameter represented by this descriptor.
 String getName()
          Retrieve the localized name of the transformation item.
 int getOrdinal()
           Retrieves the ordinal of the parameter in the list of parameters for the pattern.
 AbstractPatternDefinition getOwningDefinition()
          Returns the owning definition for this parameter.
 IPatternIdentity getPatternIdentity()
          Retrieves the composite identity of the pattern that has the parameter represented by this descriptor.
 ITransformationProperty[] getProperties()
          Return all defined properties associated with this transformation.
 ITransformationProperty getProperty(String propertyId)
          Return the specified property associated with this transformation.
 String[] getPropertyIds()
          List the identifers of properties associated with this transformation.
 AbstractParameterArgument[] getSecondArgumentCandidates(AbstractPatternInstance instance, IPatternMetatype metatype, MultiStatus status)
           
 AbstractParameterArgument[] getSecondArgumentCandidatesForFirstValue(AbstractPatternInstance instance, IPatternMetatype metatype, AbstractParameterArgument firstValue, MultiStatus status)
           
protected  EClass getSubstituteType()
          This method takes the current type of this parameter and then potentially changes the type to a more concrete type if possible (if not concrete already).
 IPatternMetatype getType()
          Retrieves the type of the parameter represented by this descriptor.
 Object getValue(AbstractPatternInstance instance)
          For a given instance, return this value of this parameter, it assumes there is only one parameter value, this would be used as a convenience for parameters with a multiplicity of one.
 Object[] getValues(AbstractPatternInstance instance)
          For a given instance, return the values of this parameter, this method works fine for parameter's of any multiplicity.
 int hashCode()
           
 boolean hasValue(AbstractPatternInstance instance)
          For a given instance, determine if the parameter has a value or values.
 boolean hasValues(AbstractPatternInstance instance)
          For a given instance, determine if the parameter has a value or values bound.
protected  void initialize()
          A hot-spot method that is defaulted with no implementation.
 boolean isBindable()
          Retrieves whether the parameter represented by this descriptor is available for binding with an argument or arguments.
 boolean isPublic()
          Return true if the transformation is public (visible in UI).
protected  boolean isRetrievable()
          A hot-spot method that indicates if a parameter value, given a name within a scope, can be retrieved.
protected  boolean isScopeDerivable()
          Determines if this parameter has a scope that can be derived, also known as a default context or namespace for resolving elements and/or creating new parameter values.
protected  boolean isTypeSubstitutable()
          Indicates if the type of this parameter can be made more concrete and subtituted for various operations that requires a concrete type in lieu of an abstract type.
 boolean isValid(AbstractPatternInstance instance, Object value)
          Determines if a parameter value is valid given a pattern instance.
protected  boolean isValid(PatternParameterValue.Maintained maintained)
          Determines if the maintained value is valid.
protected  boolean isValid(PatternParameterValue.Proposed proposed)
          Determines if the proposed value is valid.
protected  boolean isValid(PatternParameterValue.Unresolved unresolved)
          Determines if the unresolved value is valid.
protected  boolean isValid(PatternParameterValue.Unresolved unresolved, PatternParameterValue.Unresolved.Directive directive)
          Determines if the unresolved value is valid.
 boolean isValidParameterTarget(Object targetObject)
          Indicates whether this target object is a valid parameter value for this parameter to bind to.
protected  Object resolve(PatternParameterValue.Unresolved unresolved)
          The resolve method is called if an unresolved value is attempting to be bound to this parameter.
protected  Object resolve(PatternParameterValue.Unresolved unresolved, PatternParameterValue.Unresolved.Directive directive)
          The resolve method extends upon the resolve method that does not take a directive.
protected  Object retrieve(AbstractPatternInstance instance, String valueName)
          A hot-spot method that retrieves a parameter value, given a name
 IStatus usesPairsToCreateArguments(AbstractPatternInstance instance, IPatternMetatype metatype)
          Indicates whether this parameter uses a pair of other parameter's arguments to create default arguments
protected  IStatus validToAddArgument(PatternParameterValue.Proposed proposed)
          This method is a hotspot that is overridden to add custom pattern specific argument validation logic.
protected  IStatus validToAddArgument(PatternParameterValue.Unresolved unresolved)
          This method is a hotspot that is overridden to add custom pattern specific argument validation logic.
protected  IStatus validToCreateArguments(AbstractPatternInstance instance, IPatternMetatype metatype)
          This is a hotspot method used in conjunction with the create method.
protected  IStatus validToReplaceArgument(PatternParameterValue.Proposed proposed)
          This method is a hotspot that is overridden to add custom pattern specific argument validation logic.
protected  IStatus validToReplaceArgument(PatternParameterValue.Unresolved unresolved)
          This method is a hotspot that is overridden to add custom pattern specific argument validation logic.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.ibm.xtools.patterns.core.IParameterDescriptor
isValidArgumentType
 

Constructor Detail

AbstractPatternParameter

public AbstractPatternParameter(AbstractPatternDefinition owningDefinition,
                                PatternParameterIdentity parameterIdentity)
Constructs a pattern parameter given only the parameter identity; the parameter descriptor offered by associated static pattern provider will then be attached to this parameter as the concrete descriptor state in this class.

Parameters:
owningDefinition - the owning definition for this parameter
parameterIdentity - the identity of the parameter, typically this would be the fully qualified class name of the concrete abstract pattern parameter implemented by the author

AbstractPatternParameter

public AbstractPatternParameter(AbstractPatternDefinition owningDefinition,
                                PatternParameterIdentity parameterIdentity,
                                String oclExpression)
Constructs a patterm parameter given only the parameter identity; the parameter descriptor offered by associated static pattern provider will then be attached to this parameter as the concrete descriptor state in this class.

Parameters:
owningDefinition - the owning definition for this parameter
parameterIdentity - the identity of the parameter, typically this would be the fully qualified class name of the concrete abstract pattern parameter implemented by the author
oclExpression - a valid OCL expression used for constraining the values allowable to be bound to this parameter
Method Detail

accept

public void accept(Visitor visitor)
Enable visitation of this entity.

Specified by:
accept in interface Visitable

compareTo

public int compareTo(Object object)
Specified by:
compareTo in interface Comparable

create

protected abstract Object[] create(AbstractPatternInstance instance,
                                   IPatternMetatype metatype)
If this parameter supports creation of prototypical instances then this method will be implemented. It is determined whether or not a parameter support prototypical instance creation by implementing the is creatable method so it returns true. This is a hot-spot method that is used in conjunction with the is creatable method. This method must just create values; the eventual adding of this values to the pattern instance are handled by the framework. The same is true for the resolve hot-spot method found on this class.

Parameters:
instance - the instance that defines context for creating new prototypical instances of suggested arguments of this parameter
metatype - the proposed metatype for the new prototypical arguments of this parameter; if the metatype is null then the parameter may choose an appropriate metatype
Returns:
an object array that holds all new values that were created; the types of the returned objects need to conform with the is valid checks defined by this parameter. Before the new values are added, an validation will be performed by invoking the is valid proposed value method variant.

create

protected abstract Object[] create(AbstractPatternInstance instance,
                                   IPatternMetatype metatype,
                                   String scopeQualifiedName)
If this parameter supports creation of prototypical instances then this method will be implemented. It is determined whether or not a parameter support prototypical instance creation by implementing the is creatable method so it returns true. This is a hot-spot method that is used in conjunction with the is creatable method. This method must just create values; the eventual adding of this values to the pattern instance are handled by the framework. The same is true for the resolve hot-spot method found on this class.

Parameters:
instance - the instance that defines context for creating new prototypical instances of suggested arguments of this parameter
metatype - the proposed metatype for the new prototypical arguments of this parameter; if the metatype is null then the parameter may choose an appropriate metatype
scopeQualifiedName - the qualified name that specifies the scope.
Returns:
an object array that holds all new values that were created; the types of the returned objects need to conform with the is valid checks defined by this parameter. Before the new values are added, an validation will be performed by invoking the is valid proposed value method variant.

createArgumentsUsingPairs

public Object[] createArgumentsUsingPairs(AbstractPatternInstance instance,
                                          IPatternMetatype metatype,
                                          AbstractParameterArgument.Pair[] pairs)
If this parameter supports creation of prototypical instances then this method will be implemented. It is determined whether or not a parameter support prototypical instance creation by implementing the is creatable method so it returns true. This is a hot-spot method that is used in conjunction with the is creatable method. This method must just create values; the eventual adding of this values to the pattern instance are handled by the framework. The same is true for the resolve hot-spot method found on this class.

Parameters:
instance - the instance that defines context for creating new prototypical instances of suggested arguments of this parameter
metatype - the proposed metatype for the new prototypical arguments of this parameter; if the metatype is null then the parameter may choose an appropriate metatype
pairs - - pairs of clients and suppliers which should be used to create the new element
Returns:
an object array that holds all new values that were created; the types of the returned objects need to conform with the is valid checks defined by this parameter. Before the new values are added, an validation will be performed by invoking the is valid proposed value method variant.

equals

public boolean equals(Object object)

expand

protected boolean expand(PatternParameterValue value)
A hot-spot method that can be overridden in parameter subclasses. The expand method is invoked for a particular parameter if a parameter value has been added or removed since the last time an expansion took place. The expand method will be invoked once for each singular value so if multiple values were contained within one pattern parameter value, the values will first be unraveled into singular values before the expand calls take place. This was implemented so pattern implementations could eliminate their iteration logic. This is the default general expand method that is typically implemented by concrete pattern parameters for handling the added and maintained expand variants which are usually similar. The default behavior is to return true.

Parameters:
value - the value used in the expansion
Returns:
always true unless overridden by subclasses

expand

protected boolean expand(PatternParameterValue.Added value)
A hot-spot method that can be overridden in parameter subclasses. The expand method is invoked for a particular parameter if a parameter value has been added or removed since the last time an expansion took place. The expand method will be invoked once for each singular value so if multiple values were contained within one pattern parameter value, the values will first be unraveled into singular values before the expand calls take place. This was implemented so pattern implementations could eliminate their iteration logic. By default this method turns around and invokes the more general expand method that takes a PatternParameterValue.

Parameters:
value - the value used in the expansion
Returns:
the value as returned by the general expand method
See Also:
expand(PatternParameterValue)

expand

protected boolean expand(PatternParameterValue.Maintained value)
A hot-spot method that can be overridden in parameter subclasses. The expand method is invoked for a particular parameter if a parameter value has been added or removed since the last time an expansion took place. The expand method will be invoked once for each singular value so if multiple values were contained within one pattern parameter value, the values will first be unraveled into singular values before the expand calls take place. This was implemented so pattern implementations could eliminate their iteration logic. By default this method turns around and inokes the more general expand method that takes a PatterParameterValue.

Parameters:
value - the value used in the expansion
Returns:
the value as returned by the general expand method

expand

protected boolean expand(PatternParameterValue.Removed value)
A hot-spot method that can be overridden in parameter subclasses. The expand method is invoked for a particular parameter if a parameter value has been added or removed since the last time an expansion took place. The expand method will be invoked once for each singular value so if multiple values were contained within one pattern parameter value, the values will first be unraveled into singular values before the expand calls take place. This was implemented so pattern implementations could eliminate their iteration logic. The default behavior is to return true since removed value expansion is optional but it is recommended that pattern parameters support this for consistency with the patterns shipped in the product and a better user experience for the patter applying user.

Parameters:
value - the value used in the expansion
Returns:
always true unless overridden by subclasses

expand

protected boolean expand(PatternParameterValue.Replaced value)
A hot-spot method that can be overridden in parameter subclasses. The expand method is invoked for a particular parameter if a parameter value has been replaced since the last time an expansion took place. The expand method will be invoked once for each singular value so if multiple values were contained within one pattern parameter value, the values will first be unraveled into singular values before the expand calls take place. This was implemented so pattern implementations could eliminate their iteration logic. The default behavior is to return true since replaced value expansion is optional but it is recommended that pattern parameters support this for consistency with the patterns shipped in the product and a better user experience for the patter applying user. Default behavior is to issue remove expands and then add expands for the replacement values.

Parameters:
value - the value used in the expansion
Returns:
always true unless overridden by subclasses

getAlternateTypes

public IPatternMetatype[] getAlternateTypes()
Description copied from interface: IParameterDescriptor

Retrieves the alternate types that are accepted for the arguments of the parameter represented by this descriptor.

Specified by:
getAlternateTypes in interface IParameterDescriptor
Returns:
Returns the alternate types accepted for the arguments of the parameter.

getDerivedScope

protected Object getDerivedScope(AbstractPatternInstance instance)
Retrieves the derived scope which in turn can be used to resolve parameter values and create parameter values within. A scope can also be thought of as a namespace or a context for values that need some direction as to where they are attached. A null indicates that the derived scope could not be retrieved. Normally this method should only return null if the has derived scope method returns false. This method along with the has derived scope method should be overridden in tandem. For parameter values that have no concept of being attached to a container the scope is undefined and not used.

Parameters:
instance - the pattern instance of interest for determining if a default scope is available
Returns:
the object that is the default scope, for example for UML2 this might be a UML2 package that contains the values which are UML2 classes

getDescription

public final String getDescription()
Description copied from interface: ITransformationItem
Retrieve the localized description of the transformation item.

Specified by:
getDescription in interface ITransformationItem
Returns:
String - the localized description for the transformation item.

getFirstArgumentCandidates

public AbstractParameterArgument[] getFirstArgumentCandidates(AbstractPatternInstance instance,
                                                              IPatternMetatype metatype,
                                                              MultiStatus status)

getId

public final String getId()
Description copied from interface: ITransformationItem
Retrieve the unique id of the transformation item.

Specified by:
getId in interface ITransformationItem
Returns:
String - the unique identifier for the transformation item

getMultiplicity

public final IMultiplicity getMultiplicity()
Description copied from interface: IParameterDescriptor

Retrieves the multiplicity of the parameter represented by this descriptor.

Multiplicity represents the range of the allowable cardinality values that a set can assume.

Specified by:
getMultiplicity in interface IParameterDescriptor
Returns:
Returns the multiplicity of the parameter.

getName

public final String getName()
Description copied from interface: ITransformationItem
Retrieve the localized name of the transformation item.

Specified by:
getName in interface ITransformationItem
Returns:
String - the localized name for the transformation item.

getOrdinal

public final int getOrdinal()
Description copied from interface: IParameterDescriptor

Retrieves the ordinal of the parameter in the list of parameters for the pattern.

Specified by:
getOrdinal in interface IParameterDescriptor
Returns:
Returns the ordinal of the parameter.

getOwningDefinition

public final AbstractPatternDefinition getOwningDefinition()
Returns the owning definition for this parameter.

Returns:
the definition that owns this parameter

getPatternIdentity

public final IPatternIdentity getPatternIdentity()
Description copied from interface: IParameterDescriptor

Retrieves the composite identity of the pattern that has the parameter represented by this descriptor.

The composite unique identity of a pattern is represented by a pattern descriptor. The components of the identity are the id (getPatternId) and the version of the pattern (getPatternVersion).

Specified by:
getPatternIdentity in interface IParameterDescriptor
Returns:
Returns the identity of the pattern that has the parameter represented by this descriptor.

getProperties

public final ITransformationProperty[] getProperties()
Description copied from interface: ITransformationDescriptor
Return all defined properties associated with this transformation. This method returns all of the static properties defined for this transformation, including readonly properties. Properties defined in a transform context (@link ITransformContext) are not returned by this method. Each associated property defines the default value, which cannot be changed. However the values for non-readonly properties can be overridden in the transform context.

Specified by:
getProperties in interface ITransformationDescriptor
Returns:
TransformationProperty[] - an array of defined properties

getProperty

public final ITransformationProperty getProperty(String propertyId)
Description copied from interface: ITransformationDescriptor
Return the specified property associated with this transformation. If the property is not defeind for this transformation, null is returned.

Specified by:
getProperty in interface ITransformationDescriptor
Parameters:
propertyId - the identifier of the property
Returns:
ITransformationProperty - the property, if defined

getPropertyIds

public final String[] getPropertyIds()
Description copied from interface: ITransformationDescriptor
List the identifers of properties associated with this transformation. This list contains only those properties that have been defined and does not include any new properties defined in a transform context (@link ITransformContext).

Specified by:
getPropertyIds in interface ITransformationDescriptor
Returns:
String[] - the identifiers of associated properties

getSecondArgumentCandidates

public AbstractParameterArgument[] getSecondArgumentCandidates(AbstractPatternInstance instance,
                                                               IPatternMetatype metatype,
                                                               MultiStatus status)

getSecondArgumentCandidatesForFirstValue

public AbstractParameterArgument[] getSecondArgumentCandidatesForFirstValue(AbstractPatternInstance instance,
                                                                            IPatternMetatype metatype,
                                                                            AbstractParameterArgument firstValue,
                                                                            MultiStatus status)

getSubstituteType

protected EClass getSubstituteType()
This method takes the current type of this parameter and then potentially changes the type to a more concrete type if possible (if not concrete already). If the resultant type returned from this method is still abstract then it cannot be created by this parameter in the create method since it is not concrete. This is a hot-spot method that can be implemented to supply the correct substitute type given the real type of the parameter.

Returns:
the most concrete type available for this parameter's type; an example of using this method to get the desired behavior would be to return a UML2 interface if a UML2 classifier is the current parameter type. This would allow an interface to be created since its concrete as the default create behavior.

getType

public IPatternMetatype getType()
Description copied from interface: IParameterDescriptor

Retrieves the type of the parameter represented by this descriptor.

Use the Pair method to retrieve the argument pairs used as parameter arguments. Use the isValidArgumentType method to retrieve whether the object of a specific metatype is accepted as an argument of the parameter. Use the getAlternateTypes method to retrieve the types accepted for parameter arguments.

Specified by:
getType in interface IParameterDescriptor
Returns:
Returns the type of the parameter.

getValue

public final Object getValue(AbstractPatternInstance instance)
For a given instance, return this value of this parameter, it assumes there is only one parameter value, this would be used as a convenience for parameters with a multiplicity of one. If no parameter value is bound for this instance and parameter a null will be returned. If the value bound is a multivalue then only the first value will be returned.

Parameters:
instance - associated with value
Returns:
value of the pattern parameter for given pattern instance

getValues

public final Object[] getValues(AbstractPatternInstance instance)
For a given instance, return the values of this parameter, this method works fine for parameter's of any multiplicity. If a parameter has zero values bound then the contract is for this method is not to return null but to return an array of length zero instead.

Parameters:
instance - associated with values
Returns:
value of the pattern parameter for given pattern instance

hashCode

public int hashCode()

hasValue

public final boolean hasValue(AbstractPatternInstance instance)
For a given instance, determine if the parameter has a value or values.

Parameters:
instance - associated with value
Returns:
indicates if this parameter has a value for given pattern instance

hasValues

public final boolean hasValues(AbstractPatternInstance instance)
For a given instance, determine if the parameter has a value or values bound.

Parameters:
instance - associated with value
Returns:
indicates if this parameter has a value for given pattern instance

initialize

protected void initialize()
A hot-spot method that is defaulted with no implementation. It is recommended that all custom pattern parameter constructor code be put in the pattern parameter initialize method rather than in the constructor. This method will be invoked after the pattern definition that owns this parameter has been initialized.


isBindable

public final boolean isBindable()
Description copied from interface: IParameterDescriptor

Retrieves whether the parameter represented by this descriptor is available for binding with an argument or arguments.

A binding is a relationship connection between a template and a model element generated from the template. It provides the collection of the arguments that instantiate the template parameters. A binding is associated with one template. Each binding generates one model element. The generated model element must be fully specified by the arguments supplied to the binding.

Note: In general, if a parameter is not bindable, it should not be exposed to a user.

Specified by:
isBindable in interface IParameterDescriptor
Returns:
Returns a Boolean that has a value of True if the parameter is bindable. Otherwise, it returns a value of False.

isPublic

public final boolean isPublic()
Description copied from interface: ITransformationDescriptor
Return true if the transformation is public (visible in UI).

This is a convenience method for returning the value of the PUBLIC property.

Specified by:
isPublic in interface ITransformationDescriptor
Returns:
boolean - true for public transformations

isRetrievable

protected boolean isRetrievable()
A hot-spot method that indicates if a parameter value, given a name within a scope, can be retrieved.

Returns:
true if a parameter value is retrievable from the derived scope

isScopeDerivable

protected boolean isScopeDerivable()
Determines if this parameter has a scope that can be derived, also known as a default context or namespace for resolving elements and/or creating new parameter values. If this hot-spot method is not implemented then the get derived scope method will not be used to determine where to find or create model elements. This method and the get default scope method work together with the is creatable and create parameter methods. For parameter values that have no immediate container or owner, those that make sense to create detached, are not associated with the concept of a scope

Returns:
true if a scope for finding and creating new parameter values is derivable from the current state of the parameter, instance, etc
See Also:
getDerivedScope(AbstractPatternInstance), create(AbstractPatternInstance, IPatternMetatype)

isTypeSubstitutable

protected boolean isTypeSubstitutable()
Indicates if the type of this parameter can be made more concrete and subtituted for various operations that requires a concrete type in lieu of an abstract type. For example, the create hot-spot, etc. If this method is overridden then the complementary get substitute type should also be overridden.

Returns:
indicates if this type is substitutable with a more concrete type

isValid

public boolean isValid(AbstractPatternInstance instance,
                       Object value)
Determines if a parameter value is valid given a pattern instance.

Parameters:
instance - the pattern instance of interest
value - the value to determine validity of
Returns:
true if the proposed value is valid

isValid

protected boolean isValid(PatternParameterValue.Proposed proposed)
Determines if the proposed value is valid. By default false is returned, this can be overridden in pattern parameter implementation subclasses. This method is invoked according to whatever validation strategy is plugged in for this parameter. It could be that this method is never invoked because the governing strategy does some initial checks that first must be true before an additional invocation into the hot-spot is valid is called.

Parameters:
proposed - the proposed vlaue
Returns:
indicates if the value is valid or not

isValid

protected boolean isValid(PatternParameterValue.Maintained maintained)
Determines if the maintained value is valid. By default false is returned, this can be overridden in pattern parameter implementation subclasses. This method is invoked according to whatever validation strategy is plugged in for this parameter. It could be that this method is never invoked because the governing strategy does some initial checks that first must be true before an additional invocation into the hot-spot is valid is called.

Parameters:
maintained - the maintained vlaue
Returns:
indicates if the value is valid or not

isValid

protected boolean isValid(PatternParameterValue.Unresolved unresolved)
Determines if the unresolved value is valid. By default false is returned, this can be overridden in pattern parameter implementation subclasses. This method is invoked according to whatever validation strategy is plugged in for this parameter. It could be that this method is never invoked because the governing strategy does some initial checks that first must be true before an additional invocation into the hot-spot is valid is called.

Parameters:
unresolved - the unresolved value
Returns:
true if it is valid to bind the given unresolved value to this parameter once it has been properly resolved

isValid

protected boolean isValid(PatternParameterValue.Unresolved unresolved,
                          PatternParameterValue.Unresolved.Directive directive)
Determines if the unresolved value is valid. By default false is returned, this can be overridden in pattern parameter implementation subclasses. This method is invoked according to whatever validation strategy is plugged in for this parameter. It could be that this method is never invoked because the governing strategy does some initial checks that first must be true before an additional invocation into the hot-spot is valid is called. The additional directive parameter allows the validity logic to be altered.

Parameters:
unresolved - the unresolved value
directive - the additional directive to alter the validity logic
Returns:
true if it is valid to bind the given unresolved value to this parameter once it has been properly resolved (factoring in the directive implications)

isValidParameterTarget

public final boolean isValidParameterTarget(Object targetObject)
Indicates whether this target object is a valid parameter value for this parameter to bind to. The value validation behavior will be used to determine the return value. In the future other checks might be added since this case is a superset of the typical is valid parameter value case. In this case the target implies that a pattern instance will almost always be created as a result of a true return value here (a client of this method if they determine this target is valid will likely call back in to the create pattern instance method (the variant with a parameter in the method signature). That parameter will be this parameter being tested with this target object here. In the implementation of this method, the is valid forwarding call should pass in a void pattern instance object instead of null. For now, a null is passed in. Until the null is changed to a void pattern instance object any implementer of the is valid proposed method should not access the owning pattern instance (or at least check for null first).

Parameters:
targetObject - the object attempting to be bound
Returns:
true if the target object is a valid parameter target

resolve

protected Object resolve(PatternParameterValue.Unresolved unresolved)
The resolve method is called if an unresolved value is attempting to be bound to this parameter. If the is valid method for unresolved values return true then the resolve method on this parameter is subsequently invoked. This is a framework hot-spot method. Typically both the resolve and isValid(Unresolved) methods for a parameter would either be overridden or not overridden.

Parameters:
unresolved - the value that is in the unresolved state
Returns:
null is returned if no resolution occurs or can occur, a call to is valid for unresolves values should be made before making this call; a non-null return value indicates that the resolution took place in this parameter successfully and the native resolved value is returned, native in this context just means it is not wrapped by some pattern parameter value object

resolve

protected Object resolve(PatternParameterValue.Unresolved unresolved,
                         PatternParameterValue.Unresolved.Directive directive)
The resolve method extends upon the resolve method that does not take a directive. The directive indicates any additional instructions or restrictions that clients of the resolution action specify.

Parameters:
unresolved - the value that is in the unresolved state
directive - an additional directive that modifies behavior
Returns:
the resolved object
See Also:
resolve(PatternParameterValue.Unresolved)

retrieve

protected Object retrieve(AbstractPatternInstance instance,
                          String valueName)
A hot-spot method that retrieves a parameter value, given a name

Parameters:
instance - the instance that gives context to the retrieval
valueName - the name of the parameter value to retrieve
Returns:
the object that is the value of the specified parameter

usesPairsToCreateArguments

public IStatus usesPairsToCreateArguments(AbstractPatternInstance instance,
                                          IPatternMetatype metatype)
Indicates whether this parameter uses a pair of other parameter's arguments to create default arguments

Parameters:
instance - the pattern instance
metatype - the metatype of the arguments wanting creation
Returns:
a status indicating true if using pairs to create default arguments is valid for this parameter, instance and metatype combination

validToAddArgument

protected IStatus validToAddArgument(PatternParameterValue.Proposed proposed)
This method is a hotspot that is overridden to add custom pattern specific argument validation logic. The logic is augmented by the default logic of the appropriately selected validation strategy. By default, the validation strategy is code validation and checks upper bound multiplicity and type conformance. Implementing this hotspot does not eclipse the default behavior validation checks but simply AND'd to them. If the other default checks pass then this method is called and pattern specific logic can determine if this argument is valid or not.

Parameters:
proposed - the proposed value to validate
Returns:
a status indicating true if valid

validToAddArgument

protected IStatus validToAddArgument(PatternParameterValue.Unresolved unresolved)
This method is a hotspot that is overridden to add custom pattern specific argument validation logic. The logic is augmented by the default logic of the appropriately selected validation strategy.

Parameters:
unresolved - the unresolved value to determine if resolution into a valid argument is possible
Returns:
a status true if valid

validToCreateArguments

protected IStatus validToCreateArguments(AbstractPatternInstance instance,
                                         IPatternMetatype metatype)
This is a hotspot method used in conjunction with the create method. These two methods are complementary just as the isRetrievable and retrieve methods are. This method determines if it is valid to create default arguments of the given type for the specified pattern instance.

Parameters:
instance - the pattern instance of interest
metatype - the metatype corresponding to the arguments to create
Returns:
a status indicating true if valid

validToReplaceArgument

protected IStatus validToReplaceArgument(PatternParameterValue.Proposed proposed)
This method is a hotspot that is overridden to add custom pattern specific argument validation logic. The logic is augmented by the default logic of the appropriately selected validation strategy. By default, the validation strategy is code validation and checks upper bound multiplicity and type conformance. Implementing this hotspot does not eclipse the default behavior validation checks but simply AND'd to them. If the other default checks pass then this method is called and pattern specific logic can determine if this argument is valid or not.

Parameters:
proposed - the proposed value to validate
Returns:
a status indicating true if valid

validToReplaceArgument

protected IStatus validToReplaceArgument(PatternParameterValue.Unresolved unresolved)
This method is a hotspot that is overridden to add custom pattern specific argument validation logic. The logic is augmented by the default logic of the appropriately selected validation strategy.

Parameters:
unresolved - the unresolved value to determine if resolution into a valid argument is possible
Returns:
a status true if valid

IBM Rational Software Modeler
Release 6.0


Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2004. All rights reserved.