blackboard.base
Class BbEnum

java.lang.Object
  extended by blackboard.base.BbEnum
All Implemented Interfaces:
java.io.Serializable, java.lang.Comparable<java.lang.Object>
Direct Known Subclasses:
Announcement.Type, BbAttribute.Type, BbLabeledEnum, BbLocale.Date, BbLocale.Name, BbLocale.NameColumnOrder, BbLocale.Time, CalendarEntry.Type, Cartridge.Type, ChildFile.Action, CloneCallback.Stage, CloneConfig.Area, ConferenceOwner.OwnerType, Content.ContentView, Content.RenderType, ContentFile.Action, Course.ContentView, Course.Duration, Course.Enrollment, Course.NavStyle, Course.Pace, Course.ServiceLevel, CourseMembership.Role, CourseToc.Target, CourseUpload.Status, FormattedText.Type, IAdminObject.RecStatus, IAdminObject.RowStatus, Link.ReferredToType, Link.ReferrerType, ListFilter.Comparison, LOItem.Status, Message.MessageLifecycle, UploadedFile.Action, User.EducationLevel, User.Gender, User.InstRole, User.SystemRole, UserForumSettings.ForumRole

public abstract class BbEnum
extends java.lang.Object
implements java.lang.Comparable<java.lang.Object>, 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
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.
 java.lang.String getFieldName()
          A simple bean-based wrapper around the method toFieldName() which allows the field name to be accessed as a bean property.
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.


getFieldName

public java.lang.String getFieldName()
A simple bean-based wrapper around the method toFieldName() which allows the field name to be accessed as a bean property.


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<java.lang.Object>
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()
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

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


Copyright 2011 Blackboard, Inc. All Rights Reserved.