blackboard.base
Class BbEnum

java.lang.Object
  blackboard.base.BbEnum

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable

Direct Known Subclasses:

Announcement.Type, BbAttribute.Type, BbLabeledEnum, CalendarEntry.Type, ChildFile.Action, Content.RenderType, ContentFile.Action, ContentFile.StorageType, Course.Duration, Course.Enrollment, Course.NavStyle, Course.Pace, Course.ServiceLevel, CourseDocument.Area, CourseDocument.Type, CourseMembership.Role, CourseToc.Target, CourseUpload.Status, FormattedText.Type, GenericFieldFilter.Comparison, Link.ReferredToType, Link.ReferrerType, ReportingPeriod, UploadedFile.Action, User.EducationLevel, User.Gender, User.InstRole, User.SystemRole

public abstract class BbEnum
extends java.lang.Object
implements java.lang.Comparable, java.io.Serializable

Base enumeration class for fixed enumerations. Any type-safe enumerations defined in the API will inherit from this class. Transformation to and from string form are supported to support persistence operations. This class also implements comparable to allow enumeration elements to be sorted.

Note: This class is typically only used by Blackboard code, and should be treated as unstable. Third party interaction with enumerations will be with the various sub-classes, e.g., User.Gender.

Since:

Bb 5.5

Version:

$Revision: #1 $ $Date: 2005/06/27 $

See Also:

Serialized Form

Constructor Summary

protected

BbEnum(java.lang.String enumFieldName) Constructor

Method Summary

int	compareTo(java.lang.Object obj) The sole method of the Comparable interface.
protected static BbEnum	defineAlias(BbEnum element) Define a value as a pointer to another value.
protected static BbEnum	defineDefault(BbEnum element) Sets the default object for the enumeration.
static BbEnum	fromExternalString(java.lang.String externalString, java.lang.Class enumClass) Returns the BbEnum element specified by the externalString in the target enumeration class, enumClass.
static BbEnum	fromFieldName(java.lang.String fieldName, java.lang.Class enumClass) Returns the BbEnum element specified by the fieldName in the target enumeration class, enumClass.
static BbEnum	fromFieldName(java.lang.String fieldName, java.lang.Class enumClass, boolean returnDefault) Returns the BbEnum element specified by the fieldName in the target enumeration class, enumClass.
static BbEnum	getDefaultElement(java.lang.Class enumClass) Returns the first element in the enumeration where isDefault() is true.
static BbEnum[]	getValues(java.lang.Class enumClass) Returns an array of all of the elements in the target enumeration class specified by enumClass.
boolean	isDefault() Returns true if this is a default element.
java.lang.Object	readResolve() Serialization over-ride to ensure that a serialized object obeys object identify as defined for the BbEnum class.
java.lang.String	toExternalString() Returns an external representation of this element in the enumeration.
java.lang.String	toFieldName() Returns the short representation of this element in the enumeration.
java.lang.String	toString() Returns the String representation of this element in the enumeration.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

BbEnum

protected BbEnum(java.lang.String enumFieldName)

Constructor

Method Detail

getValues

public static BbEnum[] getValues(java.lang.Class enumClass)

Returns an array of all of the elements in the target enumeration class specified by enumClass. The array will be of the same type as the given enumeration class.

fromExternalString

public static BbEnum fromExternalString(java.lang.String externalString,
                                        java.lang.Class enumClass)

Returns the BbEnum element specified by the externalString in the target enumeration class, enumClass.

Throws:

java.lang.IllegalArgumentException - if the given string is not an external representation of one of the elements in the target enumeration class.

java.lang.IllegalArgumentException - if the given enumeration class does not extend BbEnum

fromFieldName

public static BbEnum fromFieldName(java.lang.String fieldName,
                                   java.lang.Class enumClass)

Returns the BbEnum element specified by the fieldName in the target enumeration class, enumClass. This should be used ONLY when the container class is well-defined externally.

Throws:

java.lang.IllegalArgumentException - if the given string is not a short representation of one of the elements in the target enumeration class.

java.lang.IllegalArgumentException - if the given enumeration class does not extend BbEnum

fromFieldName

public static BbEnum fromFieldName(java.lang.String fieldName,
                                   java.lang.Class enumClass,
                                   boolean returnDefault)

Returns the BbEnum element specified by the fieldName in the target enumeration class, enumClass. This should be used ONLY when the container class is well-defined externally.

Throws:

java.lang.IllegalArgumentException - if the given string is not a short representation of one of the elements in the target enumeration class.

java.lang.IllegalArgumentException - if the given enumeration class does not extend BbEnum

toExternalString

public java.lang.String toExternalString()

Returns an external representation of this element in the enumeration. This string may be used to recover the enumeration element via the fromExternalString() method.

toFieldName

public java.lang.String toFieldName()

Returns the short representation of this element in the enumeration. This string may be used to recover the enumeration element via the fromFieldName() method. This should be used ONLY when the container class is well-defined externally.

toString

public java.lang.String toString()

Returns the String representation of this element in the enumeration.

Overrides:

toString in class java.lang.Object

compareTo

public int compareTo(java.lang.Object obj)
              throws java.lang.ClassCastException

The sole method of the Comparable interface. BbEnum elements are sorted by their external string representation in alphabetical order.

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

obj - the object to be compared to.

Returns:

a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Throws:

java.lang.ClassCastException - thrown if the specified object's type prevents it from being compared to this Object

readResolve

public java.lang.Object readResolve()
                             throws java.io.ObjectStreamException

Serialization over-ride to ensure that a serialized object obeys object identify as defined for the BbEnum class.

Returns:

Canonical instance, based on the _externalString representation

Throws:

java.io.ObjectStreamException

isDefault

public boolean isDefault()

Returns true if this is a default element.

defineDefault

protected static BbEnum defineDefault(BbEnum element)

Sets the default object for the enumeration.

Parameters:

element - Object to set as default.

Returns:

Returns the element just set as default, with appropriate flags edited.

defineAlias

protected static BbEnum defineAlias(BbEnum element)

Define a value as a pointer to another value. For example,

 public static final CourseMembership.Role NONE = (CourseMembership.Role) defineAlias( STUDENT );
 

The end result is simply that CourseMembership.Role.NONE == CourseMembership.Role.STUDENT

Parameters:

element - Object to alias

Returns:

element parameter.

getDefaultElement

public static BbEnum getDefaultElement(java.lang.Class enumClass)
                                throws java.lang.IllegalArgumentException

Returns the first element in the enumeration where isDefault() is true.

Parameters:

enumClass - Enumeration class to get default value for.

Returns:

First element in the associated enumeration that is flagged as default. If no default element exists, null is returned.

Throws:

java.lang.IllegalArgumentException