com.starbase.starteam
Class Property

java.lang.Object
  |
  +--com.starbase.starteam.CacheRef
        |
        +--com.starbase.starteam.Property

All Implemented Interfaces:

java.lang.Cloneable

public class Property

extends CacheRef

Each different Type supported by a StarTeam Server (e.g. File, Change Request, Topic...) has an associated set of properties. The Property class provides information about a Type's property.

Nested Class Summary

static interface

Property.Types Constants identifying the value type of a property.

Method Summary

static boolean	areValuesEqual(java.lang.Object v1, java.lang.Object v2) Compares two property values for equality.
java.lang.Object	coerce(java.lang.Object value) Converts property values to the appropriate type when possible.
Property	copy() Creates a copy of this property object.
boolean	equals(java.lang.Object source) returns true if this object instance is equal to the source
int	getClassIDOfValue() Returns the class ID for values of this property.
java.lang.Object	getDefaultValue() Returns the default value for this property.
Property[]	getDependentProperties() Returns the set of properties that the computation of this property's value depends upon.
java.lang.String	getDisplayName() Returns this property's display name.
java.lang.String	getDisplayValue(java.lang.Object value) Converts the given property value to a string suitable for display.
boolean	getEnumDisabled(int code) Returns true if the given enumerated value has been marked disabled.
java.lang.String	getEnumDisplayName(int code) Return the display name for the enumerated value with the specified code.
EnumeratedValue[]	getEnumeratedValues() Returns an array of all the enumerated values for this property.
Translations	getEnumTranslations(int code) Returns a copy of the Translations for the specified enumerated value.
int[]	getEnumValues() Returns an array of all the enumerated values for this property.
int	getID() Returns this property's internal ID.
int	getMaxLength() For text-valued properties, returns the maximum number of characters permitted.
java.lang.String	getName() Returns this property's internal name.
Translations	getTranslations() Returns a copy of the display name translations for this property.
Type	getType() Returns the Type object than has this property as one of its properties.
int	getTypeCode() Returns the type code (e.g.
int	hashCode() returns a unique hash for all instances of this type
boolean	isAdvanced() Return true is the property is considered "advanced".
boolean	isCalculated() Returns true if the property is calculated on-the-fly by the server as opposed to being stored on the server.
boolean	isClientCalculated() Return true is the property is calculated in the fly by the client.
boolean	isDescriptor() Returns true if the property is considered a descriptor.
boolean	isDisabled() Return true if the property is flagged as disabled.
boolean	isEqualTo(Property property) Compares two Property objects.
boolean	isGenericCalculated() Returns true if the property is calculated on the server by the component.
boolean	isHeader() Returns true if this property is stored in the repository database and if the database field is a header field.
boolean	isInstance(java.lang.Object object) Returns true if the specified object is a legal value for this property.
boolean	isPrimaryDescriptor() Return true if this property is the primary descriptor for this property's owning type.
boolean	isRequired() Returns true if a value for this property is required; valid for user-defined properties only.
boolean	isRestricted() Return true if this is a restricted property.
boolean	isRevisionIndependent() Returns true if this property is revision-independent (for example, "FlagUserList", "ReadStatusUserList").
boolean	isServerCalculated() Return true if the property if caclulated on the fly by the server.
boolean	isStored() Returns true if the property is stored in the server's database.
boolean	isSysDefined() Returns true if the property is a built-in StarTeam property (as opposed to a custom property).
boolean	isTimeTruncated() Returns true if the time part of this property should be truncated during display; valid for time-valued properties only.
boolean	isUserCustomized() Returns true if this property is a user defined property.
boolean	isUserDefined() Returns true is the property was user defined through the repository customization feature.
boolean	isUserModifiable() Return true if the property is flagged as user modifiable.
boolean	isViewSpecific() Returns true if this property is view-specific (for example, "ExclusiveLocker", "BranchOnChange").
static Property[]	resolveAllDependencies(Property[] props) This will return the full set of dependent properties based on the specified set.
java.lang.String	toDebugString() Returns a String represetation of this property that may be useful for debugging purposes.
java.lang.String	toString() Returns the name of the property.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Method Detail

getType

public Type getType()

Returns the Type object than has this property as one of its properties.

Returns:

the Type object that "owns" this property.

getEnumDisplayName

public java.lang.String getEnumDisplayName(int code)

Return the display name for the enumerated value with the specified code. This will throw an IllegalArgumentException if the code is not a valid enum for this Property.

Parameters:

code - the enumerated value code

Returns:

the display name String for the specified code.

See Also:

Property.getEnumValues(), Property.getEnumDisabled(int)

getEnumTranslations

public Translations getEnumTranslations(int code)

Returns a copy of the Translations for the specified enumerated value. Will return null if the property is client calculated.

getEnumDisabled

public boolean getEnumDisabled(int code)

Returns true if the given enumerated value has been marked disabled. This will throw an IllegalArgumentException if the code is not a valid enum for this Property.

Parameters:

code - the enumerated value code

Returns:

true if the enumerated value has been marked disabled, and false otherwise.

See Also:

Property.getEnumValues(), Property.getEnumDisplayName(int)

getEnumValues

public int[] getEnumValues()

Returns an array of all the enumerated values for this property.

Returns:

an array of integer enum codes.

Throws:

java.lang.RuntimeException - if this Property Type is not an EnumeratedProperty instance

See Also:

Property.getEnumDisplayName(int), Property.getEnumDisabled(int)

getEnumeratedValues

public EnumeratedValue[] getEnumeratedValues()

Returns an array of all the enumerated values for this property. The returned EnumeratedValue objects will all have Translations even when talking to older servers. However, the those Translations from older servers will only have a default value specified. The EnumeratedValue's getEnabled value will be properly set as well.

Returns:

an array of EnumeratedValue objects

getID

public int getID()

Returns this property's internal ID.

Returns:

this property's internal ID.

getName

public java.lang.String getName()

Returns this property's internal name.

Returns:

this property's internal name.

getDisplayName

public java.lang.String getDisplayName()

Returns this property's display name.

Returns:

this property's display name.

getTranslations

public Translations getTranslations()

Returns a copy of the display name translations for this property. Will return null for client calculated properties. When working against servers that do not support display name translations the returned Translations object will only have the default value set.

getTypeCode

public int getTypeCode()

Returns the type code (e.g. USER_ID) for this property.

Returns:

this property's type code.

See Also:

Property.Types

getClassIDOfValue

public int getClassIDOfValue()

Returns the class ID for values of this property.

Returns:

the class ID for values of this property.

See Also:

Property.Types.OBJECT_ID

getMaxLength

public int getMaxLength()

For text-valued properties, returns the maximum number of characters permitted.

Returns:

The maximum number of characters permitted.

See Also:

Property.Types.TEXT

getDefaultValue

public java.lang.Object getDefaultValue()

Returns the default value for this property.

Returns:

the property's default value.

isStored

public boolean isStored()

Returns true if the property is stored in the server's database. (Some properties may be stored and others calculated on the fly by either the client or server).

Returns:

true if the property is stored in the server's database.

isCalculated

public boolean isCalculated()

Returns true if the property is calculated on-the-fly by the server as opposed to being stored on the server.

Returns:

true if this property is caclulated by the server rather than stored in the db

isHeader

public boolean isHeader()

Returns true if this property is stored in the repository database and if the database field is a header field.

Returns:

true if this property is stored in a header field in the database

isSysDefined

public boolean isSysDefined()

Returns true if the property is a built-in StarTeam property (as opposed to a custom property).

Returns:

true if the property is a built-in StarTeam property.

isUserDefined

public boolean isUserDefined()

Returns true is the property was user defined through the repository customization feature.

Returns:

true if the property is user defined.

isClientCalculated

public boolean isClientCalculated()

Return true is the property is calculated in the fly by the client.

Returns:

true if the property is client calculated.

isServerCalculated

public boolean isServerCalculated()

Return true if the property if caclulated on the fly by the server.

Returns:

true if the property if server calculated.

isGenericCalculated

public boolean isGenericCalculated()

Returns true if the property is calculated on the server by the component.

Returns:

true if the property is calculated on the server by the component.

isPrimaryDescriptor

public boolean isPrimaryDescriptor()

Return true if this property is the primary descriptor for this property's owning type. Each Type can have only one primary descriptor.

Returns:

true if the property if the primary descriptor.

isDescriptor

public boolean isDescriptor()

Returns true if the property is considered a descriptor. A Type may have multiple descriptors.

Returns:

true is this property is a descriptor.

isUserModifiable

public boolean isUserModifiable()

Return true if the property is flagged as user modifiable. This is not enforced so some properties that are marked as non-modifiable can actually be modified. This is more of a clue for the StarTeam GUI whether or not to allow the user to edit the property.

Returns:

true is the property is flagged as user modifiable.

isAdvanced

public boolean isAdvanced()

Return true is the property is considered "advanced". Generally this means the property is used internally and would be meaningless to an end user.

Returns:

true if the property is considered advanced.

isDisabled

public boolean isDisabled()

Return true if the property is flagged as disabled. Generally disabled properties should not be displayed nor edited by end users.

Returns:

true is the property is flagged as disabled.

isRestricted

public boolean isRestricted()

Return true if this is a restricted property.

Returns:

true if this is a restricted property.

isUserCustomized

public boolean isUserCustomized()

Returns true if this property is a user defined property.

Returns:

true if this property is a user defined property.

isRequired

public boolean isRequired()

Returns true if a value for this property is required; valid for user-defined properties only.

Returns:

true if a value for this property is required; valid for user-defined properties only.

isTimeTruncated

public boolean isTimeTruncated()

Returns true if the time part of this property should be truncated during display; valid for time-valued properties only.

Returns:

true if the time part of this property should be truncated during display; valid for time-valued properties only.

isViewSpecific

public boolean isViewSpecific()

Returns true if this property is view-specific (for example, "ExclusiveLocker", "BranchOnChange"). Used only for server-calculated properties. Available only for StarTeam server versions 5.1 and later.

Returns:

true if this property is view-specific (for example, "ExclusiveLocker", "BranchOnChange"). Used only for server-calculated properties. Available only for StarTeam server versions 5.1 and later.

isRevisionIndependent

public boolean isRevisionIndependent()

Returns true if this property is revision-independent (for example, "FlagUserList", "ReadStatusUserList"). Used only for server-calculated properties. Available only for StarTeam server versions 5.1 and later.

Returns:

true if this property is revision-independent (for example, "FlagUserList", "ReadStatusUserList"). Used only for server-calculated properties. Available only for StarTeam server versions 5.1 and later.

isInstance

public boolean isInstance(java.lang.Object object)

Returns true if the specified object is a legal value for this property.

Parameters:

object - the object being checked as a legal value for this property.

Returns:

true is the specified object is a legal value for this property.

getDependentProperties

public Property[] getDependentProperties()

Returns the set of properties that the computation of this property's value depends upon. If none, the list will be empty (will not return null). Only client calculated properties will have dependencies. It is possible that one of the returned properties also has dependencies.

Returns:

the properties that this property depends upon

See Also:

Property.resolveAllDependencies(com.starbase.starteam.Property[]), Property.isClientCalculated()

resolveAllDependencies

public static Property[] resolveAllDependencies(Property[] props)

This will return the full set of dependent properties based on the specified set. The returned set will include the specified properties. The returned set will not have duplicate elements.

See Also:

Property.getDependentProperties()

coerce

public java.lang.Object coerce(java.lang.Object value)
                        throws java.lang.ClassCastException

Converts property values to the appropriate type when possible. For example, a property whose value is an Integer one may pass in a Byte or Short without precision loss. This method will return the approrpate value when possible or throw a ClassCastException when not. The supported conversions are as follows:

Integer: values will accept Integer, Short, or Byte

Double: values will accept Number (and consequently Double, Long, Float, Integer, Short, Byte)

OLEDate: values will accept OLEDate and java.util.Date

Parameters:

value - the property value to be coerced to the proper type. This cannot be null.

Returns:

the coerced value. It may remain unchanged if of the proper type already.

Throws:

java.lang.ClassCastException - if the type coercion can not be performed

toString

public java.lang.String toString()

Returns the name of the property.

Overrides:

toString in class java.lang.Object

Returns:

the name of the property.

toDebugString

public java.lang.String toDebugString()

Returns a String represetation of this property that may be useful for debugging purposes.

Returns:

a debug string for this property.

copy

public Property copy()

Creates a copy of this property 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.

For enumerated properties, the enumerated values are copied.

For client-calculated properties, the individual property objects that are included in the list of dependent properties are not copied.

Returns:

A copy of this property object.

See Also:

Property.isEqualTo(com.starbase.starteam.Property)

isEqualTo

public boolean isEqualTo(Property property)

Compares two Property objects.

The parent Types are compared by ClassID.

For enumerated properties, the enumerated values are compared using a deep comparison.

For client-calculated properties, the two Property objects must have the same dependents. Dependent properties are compared by property ID.

Returns:

true if no differences were found.

See Also:

Property.copy()

areValuesEqual

public static boolean areValuesEqual(java.lang.Object v1,
                                     java.lang.Object v2)

Compares two property values for equality. Handles all StarTeam data types in a "natural" fashion. For example, two IDARRAY values are considered equal if they contain the same IDs in the same order.

Parameters:

v1 - Property value.

v2 - Another property value.

Returns:

true if the two values are equal.

getDisplayValue

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

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

Parameters:

value - A legal value for this property.

Returns:

A string representation of the value

equals

public boolean equals(java.lang.Object source)

returns true if this object instance is equal to the source

Overrides:

equals in class java.lang.Object

Parameters:

source - Object the source to comapre with

Returns:

boolean true if this object is equal to the source

hashCode

public int hashCode()

returns a unique hash for all instances of this type

Overrides:

hashCode in class java.lang.Object

Returns:

int a unique hash for all instances of this type