com.starteam
Class EnumeratedProperty

java.lang.Object
  com.starteam.Property
      com.starteam.EnumeratedProperty

All Implemented Interfaces:

java.lang.Cloneable

Direct Known Subclasses:

Audit.Type.EventIDProperty, BooleanProperty, Change.Type.ActionProperty, Change.Type.ChangeTypeProperty, ChangePackage.Type.SessionTypeProperty, ChangePackage.Type.StateProperty, ChangeRequest.Type.ChangeRequestTypeProperty, ChangeRequest.Type.PlatformProperty, ChangeRequest.Type.PriorityProperty, ChangeRequest.Type.SeverityProperty, ChangeRequest.Type.StatusProperty, ChangeRequest.Type.StreamStateProperty, File.Type.CharacterSetProperty, File.Type.CompressionProperty, File.Type.EOLFormatProperty, File.Type.KeywordFlagProperty, File.Type.StatusProperty, File.Type.StorageTypeProperty, Folder.Type.ExcludeFlagsProperty, Folder.Type.StatusProperty, Group.Type.TypeProperty, Item.Type.TagProperty, Project.Type.EncryptionAlgorithmProperty, Project.Type.MethodologyProperty, Project.Type.StatusProperty, Requirement.Type.PriorityProperty, Requirement.Type.RequirementTypeProperty, Requirement.Type.StatusProperty, Requirement.Type.StreamStateProperty, Requirement.Type.UDAGroupingProperty, Story.Type.IncomingStreamProperty, Story.Type.RiskProperty, Story.Type.StatusProperty, Story.Type.StoryTypeProperty, Story.Type.StoryValueProperty, Story.Type.StreamStateProperty, Task.Type.ConstraintProperty, Task.Type.LifeCycleTypeProperty, Task.Type.OriginProperty, Task.Type.PriorityProperty, Task.Type.ProcessUsageProperty, Task.Type.StatusProperty, Task.Type.TaskTypeProperty, TaskDependency.Type.PredecessorTypeProperty, Topic.Type.PriorityProperty, Topic.Type.StatusProperty, Topic.Type.TopicTypeProperty, Trace.Type.StatusProperty, Trace.Type.TraceTypeProperty, TreeItem.Type.MoSCoWProperty, TypedResource.Type.BranchStateProperty, User.Type.LicenseTypeProperty, User.Type.StatusProperty, User.Type.TerritoryProperty, View.Type.TypeProperty, ViewCompareMergeProperty, ViewMember.Type.MyLockProperty, ViewMember.Type.ShareStateProperty

public class EnumeratedProperty
extends Property

This class represents a property whose value is an enumeration Historically, enumerations were single select, i.e. only a single enumerated value could be sent to or received from the starteam server, in the context of an EnumeratedProperty. However, from StarTeam server 12.0 on, the server supports multi select enumerated lists. i.e. an application may create a custom multi-select enumerated property and send/receive more than one enumerations as the value of the property for the artifact For consistency, the SDK api TypedResource.getValue(Property) always returns an array of EnumeratedValue's, whether the property type is single or multi-select. For single select, the array will contain 0 or 1 enumerated value's (depending upon whether any value has been selected or not) For multi select lists, the array will contain 0 or more enumerated values. For EnumeratedProperties, the SDK api TypedResource.setValue(Property, Object) takes either a single Enumerated Value or an array of EnumeratedValues in the second parameter. If a single value is presented, a single value is saved irrespective of whether the list is single or multi select. On the other hand, if an array of values (> 1) is presented, but the property type is single select, an SKDRuntimeException will be thrown

See Also:

EnumeratedValue

Nested Class Summary

static class

EnumeratedProperty.WebCacheEnumeratedProperty Base accessor for cached SDK objects encapsulating the statefulness of objects obtained from the artifact cache.

Nested classes/interfaces inherited from class com.starteam.Property

Property.MetaData, Property.WebCacheProperty

Field Summary

static int

VALUE_NOT_SET Represents "value not set" for an EnumeratedProperty.

Method Summary

Property	copy() Creates a copy of this EnumeratedProperty object.
EnumeratedValue	createValue(java.lang.String displayName) Create a new Enumerated Value for this property.
EnumeratedValue	findValue(int enumCode) Finds an existing EnumeratedValue by code.
EnumeratedValue	findValue(java.lang.String internalName) Finds an existing EnumeratedValue by internal name.
EnumeratedValue[]	getAllValues() A convenience method for returning an array of the possible values of an enumerated property.Optimized to run internal queries just once to build up the list of all values
EnumeratedValue[]	getDefaultValues() Returns the default array of enumerated values for this Property.
java.lang.String	getDisplayValue(java.lang.Object value) Converts the given property value to a string suitable for display.
java.lang.String	getEnumDisplayName(int value) A convenience method for returning the display name for a given value of an enumerated property.
EnumeratedValue[]	getSortedValues() Returns an array of all the enumerated values for this property, sorted by the specified sort order
EnumeratedValue[]	getValues() Returns an array of the enumerated values of this property.
boolean	isEqualTo(Property property) Compares two EnumeratedProperty objects.
boolean	isHierarchicalEnumeration() Returns true if at least one of the enumerated values has child values, or false if every enumerated value is a root value with no children
boolean	isMultiSelectable() Returns true if this Enumerated Property supports selecting more than one enumerated value at a time.
boolean	isQueryRelationSupported(QueryPart.Relation operator) Returns true if this property supports the specified query operator(s)
boolean	isStatusProperty() Returns true if this Enumerated Property is the status property for the owning type.
QueryPart	newQueryPart(QueryPart.Relation relation, EnumeratedValue value) Creates a new query expression that tests this property.
QueryPart	newQueryPart(QueryPart.Relation relation, EnumeratedValue[] values) Creates a new query expression that tests this property.
QueryPart	newQueryPart(QueryPart.Relation relation, int value) Returns a new QueryPart that tests this property against the given value using the given query relation
void	setDefaultValues(EnumeratedValue[] defaultValues) Sets an array of enumerated values to be the default for the property.
void	setStatusProperty(boolean enable) set this property to be the status property for the owning type.
void	setValues(EnumeratedValue[] values) Sets an array of the enumerated values for this property Applications that track sort order, indentation, etc on their own and/or create enumerated values using the standard constructors must use this api to assign all enumerated values to the enumerated property Applications that use this EnumeratedProperty itself to auto generate enum codes and use the EnumeratedValue helper api's such as EnumeratedValue.addChild(EnumeratedValue) or EnumeratedValue.setAfter(EnumeratedValue) can directly update this property when done, without calling this method.
BooleanProperty	toBooleanProperty(EnumeratedValue falseValue, EnumeratedValue trueValue) Convert an existing EnumeratedProperty into a BooleanProperty
void	update() If this property is new or dirty, saves changes to the repository

Methods inherited from class com.starteam.Property

areValuesEqual, equals, getDebugString, getDependentProperties, getDisplayName, getDisplayNameTranslations, getGenericDefaultValue, getID, getName, getServer, getType, hashCode, isAdvanced, isCalculated, isClientCalculated, isDescriptor, isDirty, isDisabled, isEnabled, isGenericCalculated, isHeader, isItemProperty, isLegalValue, isNew, isPrimaryDescriptor, isRequired, isRestricted, isRevisionIndependent, isServerCalculated, isSortByTextValueSupported, isStored, isSysDefined, isUserCustomized, isUserDefined, isUserModifiable, isViewSpecific, resolveAllDependencies, setDescriptor, setDisplayName, setDisplayNameTranslations, setEnabled, setGenericDefaultValue, setPrimaryDescriptor, setRequired, toString, toXml

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

VALUE_NOT_SET

public static final int VALUE_NOT_SET

Represents "value not set" for an EnumeratedProperty.

See Also:

Constant Field Values

Method Detail

getDefaultValues

public EnumeratedValue[] getDefaultValues()

Returns the default array of enumerated values for this Property. Single select enumerated property can have at most one default value, while multi-select enumerated property can have multiple values selected as default.

Returns:

the default EnumeratedValues

setDefaultValues

public void setDefaultValues(EnumeratedValue[] defaultValues)

Sets an array of enumerated values to be the default for the property. Multiple default values can be set for multi-select enumerated property.

Parameters:

defaultValues - the new array of default values

Throws:

SDKRuntimeException - if attempting to set multiple defaults for single select enumerated property.

getSortedValues

public EnumeratedValue[] getSortedValues()

Returns an array of all the enumerated values for this property, sorted by the specified sort order

Returns:

a sorted array of all the enumerated values for this property

toBooleanProperty

public BooleanProperty toBooleanProperty(EnumeratedValue falseValue,
                                         EnumeratedValue trueValue)

Convert an existing EnumeratedProperty into a BooleanProperty

The old EnumeratedProperty is replaced by the new BooleanProperty within the parent Type's properties collection. The new property is dirty; to save changes, you must call Property.update(). The old property is invalid and should be discarded.

Parameters:

falseValue - The EnumeratedValue that represents False

trueValue - The EnumeratedValue that represents True

Returns:

The converted BooleanProperty

getValues

public EnumeratedValue[] getValues()

Returns an array of the enumerated values of this property.

For hierarchical enumerations, only root enumerated values are listed. Other values may be found by traversing the enum hierarchy

Returns:

An array of the enumerated values of this property.

createValue

public EnumeratedValue createValue(java.lang.String displayName)

Create a new Enumerated Value for this property. Automatically assign the next sequential enum code to this new enum and assign the context of the enumerated property to simplify usage of the SDK api's, and eliminate the overhead of the call to setValues(), which requires client tracking the state of all changes to Enumerated Values

Parameters:

displayName - the display name for the new value

Returns:

a new Enumerated Value for this property

isHierarchicalEnumeration

public boolean isHierarchicalEnumeration()

Returns true if at least one of the enumerated values has child values, or false if every enumerated value is a root value with no children

Returns:

boolean true if at least one of the enumerated values has child values

isMultiSelectable

public boolean isMultiSelectable()

Returns true if this Enumerated Property supports selecting more than one enumerated value at a time. This feature was introduced in the 12.0 server

Returns:

true if this Enumerated Property supports selecting multiple enumerations

isStatusProperty

public boolean isStatusProperty()

Returns true if this Enumerated Property is the status property for the owning type. This feature was introduced in the 12.0 server Note that a type may have at most one status property

Returns:

true if this Enumerated Property supports selecting multiple enumerations

setStatusProperty

public void setStatusProperty(boolean enable)

set this property to be the status property for the owning type. File, Folder & Audit Types cannot be set to be process item types Note that a type may have at most one status property

Parameters:

enable - true to set this property to be the status property

findValue

public EnumeratedValue findValue(int enumCode)

Finds an existing EnumeratedValue by code. Returns null if there is no such value.

Parameters:

enumCode - the code

Returns:

an EnumeratedValue or null

findValue

public EnumeratedValue findValue(java.lang.String internalName)

Finds an existing EnumeratedValue by internal name. Returns null if there is no such value. Note that there is a distinct difference between the Display Name and the Internal Name of an Enumerated value. The display name can have associated translations in languages like French, German or Japanese. The internal name cannot, and is typically used as a key for lookups.

Parameters:

internalName - the internal name

Returns:

an EnumeratedValue or null

setValues

public void setValues(EnumeratedValue[] values)

Sets an array of the enumerated values for this property Applications that track sort order, indentation, etc on their own and/or create enumerated values using the standard constructors must use this api to assign all enumerated values to the enumerated property Applications that use this EnumeratedProperty itself to auto generate enum codes and use the EnumeratedValue helper api's such as EnumeratedValue.addChild(EnumeratedValue) or EnumeratedValue.setAfter(EnumeratedValue) can directly update this property when done, without calling this method. The helper api's automatically reassign sort order, indent levels etc on this owning property and eliminate the need for the application to do so. Note that applications which call setValues() directly are responsible for ensuring that the entire array of values passed in are correct and consistent and up-to-date w.r.t. the data they intend to save to the repository. specifically, a call to setValues() wipes out the incremental changes made by calls to the helper api's

Parameters:

values - an array of EnumeratedValue objects

getAllValues

public EnumeratedValue[] getAllValues()

A convenience method for returning an array of the possible values of an enumerated property.Optimized to run internal queries just once to build up the list of all values

Returns:

an array of the possible values for the indicated property

getEnumDisplayName

public java.lang.String getEnumDisplayName(int value)

A convenience method for returning the display name for a given value of an enumerated property. This will throw an IllegalArgumentException if the code is not valid for this Property.

Parameters:

value - one of the possible enumerated values of the indicated property

Returns:

a user-friendly display name for the given value

newQueryPart

public QueryPart newQueryPart(QueryPart.Relation relation,
                              int value)

Returns a new QueryPart that tests this property against the given value using the given query relation

Parameters:

relation - int

value - int

Returns:

QueryPart

newQueryPart

public QueryPart newQueryPart(QueryPart.Relation relation,
                              EnumeratedValue value)

Creates a new query expression that tests this property.

Parameters:

relation - The query relation.

value - The enumerated value to be tested.

Returns:

A new query expression.

isQueryRelationSupported

public boolean isQueryRelationSupported(QueryPart.Relation operator)

Returns true if this property supports the specified query operator(s)

Overrides:

isQueryRelationSupported in class Property

Parameters:

operator - Query Relation

Returns:

true if the query relation is supported by this property

newQueryPart

public QueryPart newQueryPart(QueryPart.Relation relation,
                              EnumeratedValue[] values)

Creates a new query expression that tests this property.

Parameters:

relation - The query relation.

values - The enumerated values to be tested.

Returns:

A new query expression.

getDisplayValue

public java.lang.String getDisplayValue(java.lang.Object value)

Converts the given property value to a string suitable for display.

Specified by:

getDisplayValue in class Property

Parameters:

value - A legal value for this property.

Returns:

A string representation of the value

copy

public Property copy()

Creates a copy of this EnumeratedProperty object. Useful to applications that want to save a snapshot of the Property in a given state, for example, before calling Server.refreshTypes().

The copied property will have the same parent Type as the original property. The Type object is not copied.

Overrides:

copy in class Property

Returns:

A copy of this EnumeratedProperty object.

See Also:

EnumeratedProperty.isEqualTo(com.starteam.Property)

isEqualTo

public boolean isEqualTo(Property property)

Compares two EnumeratedProperty objects. It returns true if the two are identical EnumeratedProperty objects; false, otherwise.

Overrides:

isEqualTo in class Property

Parameters:

property - the property to compare

Returns:

true if the two are identical EnumeratedProperty objects; false, otherwise.

See Also:

EnumeratedProperty.copy()

update

public void update()

If this property is new or dirty, saves changes to the repository

Overrides:

update in class Property