blackboard.data.gradebook
Class Lineitem

java.lang.Object
  blackboard.data.BbObject
      blackboard.data.gradebook.Lineitem

All Implemented Interfaces:

Available, IBbObject, java.lang.Cloneable

public class Lineitem
extends BbObject
implements Available

The Lineitem class represents a single gradable item in a course. These correspond to the Items that are defined in the user interface for the course gradebook. Included are methods for providing URL's to analysis and attempt handlers, and accessors for a String-based assessment Id. These handlers would typically be the Blackboard assessment engine, but could easily be third-party tools.

Interacting with the gradebook programmatically, typically consists of the following:

1. Instantiate a Lineitem
2. Set relevant properties on the Lineitem. courseId, pointsPossible, and title must be set before persisting.
3. Persist the Lineitem, using LineitemDbPersister

After creating the Lineitem, the task of actually recording student scores comes down to the following:

1. Creating a Score object
2. Set the relevant properties (raw score)
3. Load the associated Lineitem
4. Set the Lineitem id on the Score object
5. Persist the Score, using ScoreDbPersister

Note: Persisting a Lineitem requires the caller to have a PersistPermission with the name "OutcomeDefinition", with actions for create, modify, or delete, as appropriate. For system extensions, this is declared with a line in the manifest such as <permission type="persist" name="OutcomeDefinition" actions="create,modify,delete"/>

Note: Lineitem has completely replaced LwLineitem which has been removed from the 6.0 APIs as part of general platform development.

Since:

Bb 5.5

Version:

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

Nested Class Summary

static class

Lineitem.AssessmentLocation Simple class to define where the assessment identified by assessmentId is located.

Field Summary

static DataType

LINEITEM_DATA_TYPE Standard field used in persistence layer.

Fields inherited from class blackboard.data.BbObject

_bbAttributes

Constructor Summary

Lineitem()
Constructs and returns a new Lineitem object with date added and date changed initialized to the current date.

Lineitem(OutcomeDefinition outcomeDefinition)
Creates the Lineitem using the specified OutcomeDefinition.

Method Summary

protected void	clearAssessmentId() Clears the assessmentId and sets assessmentLocation to UNSET.
java.lang.String	getAnalysisHandlerUrl()
java.lang.Object	getAssessmentId() Returns a String-based Id for the associated assessment.
Lineitem.AssessmentLocation	getAssessmentLocation() assessmentLocation indicates whether the assessment referenced by this Lineitem is native to the Blackboard server or stored externally.
java.lang.String	getAttemptHandlerUrl() Returns the URL for this item's attemptHandler if this Lineitem points to an external assessment.
int	getColumnOrder() Returns the column position for this line item.
Id	getCourseId() Returns the Id of the Course this Lineitem is associated with.
DataType	getDataType() Returns the DataType identifier for this object.
java.util.Calendar	getDateAdded() Returns the date and time this Score was added to the gradebook.
java.util.Calendar	getDateChanged() Returns the date and time this Lineitem was modified.
Id	getId() Returns the Id associated with this BbObject.
boolean	getIsAvailable() Returns a flag describing whether students can see the item in their views of the gradebook.
java.lang.String	getName() Returns the name of the Lineitem.
OutcomeDefinition	getOutcomeDefinition() For internal use only.
float	getPointsPossible() Gets the points possible for this Lineitem
BbList	getScores() Gets all scores associated with this LineItem.
java.lang.String	getType() Returns the type of the Lineitem, for example 'Assessment' or 'Homework'.
float	getWeight() Gets the weight used in calculating cumulative scores.
void	setAnalysisHandlerUrl(java.lang.String analysisHandlerUrl)
void	setAssessmentId(java.lang.Object id, Lineitem.AssessmentLocation location) Sets the assessment Id to be used by an external assessment handler.
void	setAssessmentLocation(Lineitem.AssessmentLocation assessmentLocation) Manual over-ride for assessmentLocation.
void	setAttemptHandlerUrl(java.lang.String attemptHandlerUrl) Sets the URL to render student attempt data, if this Lineitem is set to interact with external assessment engines.
void	setColumnOrder(int iColumnOrder)
void	setCourseId(Id id) Sets the Course Id associated with this Lineitem.
void	setDateAdded() Sets the date and time this Lineitem was added to the gradebook using the current time.
void	setDateAdded(java.util.Calendar cDateAdded) Sets the date and time this Lineitem was added to the gradebook using the provided Calendar.
void	setDateChanged() Sets the date and time this Lineitem was modified using the current time.
void	setDateChanged(java.util.Calendar cDateChanged) Sets the date and time this Lineitem was modified using the provided Calendar.
protected void	setExternalAssessmentId(java.lang.String id) Sets the assessment Id to be used by an external assessment handler.
protected void	setInternalAssessmentId(Id id) Sets the assessment Id to be used by an internal assessment handler.
void	setIsAvailable(boolean bIsAvailable) Sets a flag describing whether students can see the item in their views of the gradebook.
void	setName(java.lang.String strName) Sets the name of the Lineitem.
void	setPointsPossible(float fPointsPossible) Sets the maximum points possible for this Lineitem.
void	setScores(BbList scores) Associates the input Score objects to this LineItem object.
void	setType(java.lang.String strType) Sets the type of the Lineitem.
void	setWeight(float fWeight) Sets the weight (as a percentage) for this Lineitem.
java.lang.String	toString() Returns the contents of this Lineitem object as a line-feed separated list of name value pairs of this object's properties.
void	validate() Validates the contents of this LineItem.

Methods inherited from class blackboard.data.BbObject

clone, getBbAttributes, getCreatedDate, getModifiedDate, persist, setCreatedDate, setId, setModifiedDate

Methods inherited from class java.lang.Object

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

Field Detail

LINEITEM_DATA_TYPE

public static final DataType LINEITEM_DATA_TYPE

Standard field used in persistence layer.

Constructor Detail

Lineitem

public Lineitem()

Constructs and returns a new Lineitem object with date added and date changed initialized to the current date.

Lineitem

public Lineitem(OutcomeDefinition outcomeDefinition)

Creates the Lineitem using the specified OutcomeDefinition. For internal use only.

Method Detail

getId

public Id getId()

Description copied from class: BbObject

Returns the Id associated with this BbObject.

Specified by:

getId in interface IBbObject

Overrides:

getId in class BbObject

Returns:

Id value for this BbObject

getOutcomeDefinition

public OutcomeDefinition getOutcomeDefinition()

For internal use only.

getCourseId

public Id getCourseId()

Returns the Id of the Course this Lineitem is associated with.

Returns:

A Course Id

setCourseId

public void setCourseId(Id id)

Sets the Course Id associated with this Lineitem.

Parameters:

id - A valid Course Id

getAssessmentId

public java.lang.Object getAssessmentId()

Returns a String-based Id for the associated assessment. This Id would be a standard Blackboard Id for a lineitem associated with a Blackboard assessment, and a String for a lineitem associated with an external assessment (e.g., assessmentLocation is EXTERNAL. This value would be substituted into the analysis handler URL for a third-party tool.

Returns:

The Id of the assessment this Lineitem is associated with.

setAssessmentId

public void setAssessmentId(java.lang.Object id,
                            Lineitem.AssessmentLocation location)

Sets the assessment Id to be used by an external assessment handler. This Id can be either a standard Blackboard Id or a free-form String for use by a non-Blackboard assessment handler. If setting the value for an external assessment, the type of the id parameter must be a String and the location parameter must be AssessmentLocation.EXTERNAL. if setting the value for a Blackboard assessment, the type of the id parameter must be Id and the location parameter must be AssessmentLocation.INTERNAL.

Parameters:

id - The Id of the assessment this Lineitem is associated with.

location - The location of the assessment this Lineitem is associated with.

Throws:

java.lang.IllegalArgumentException - Thrown if id and location arguments do not agree.

setInternalAssessmentId

protected void setInternalAssessmentId(Id id)

Sets the assessment Id to be used by an internal assessment handler. This Id can be either a standard Blackboard PkId or a free-form String for use by a non-Blackboard assessment handler. Note that calling this method will clear the external assessment ID, if there is one, currently associated with this Lineitem.

Parameters:

id - The Id of the assessment this Lineitem is derived from.

setExternalAssessmentId

protected void setExternalAssessmentId(java.lang.String id)

Sets the assessment Id to be used by an external assessment handler. This Id can be either a standard Blackboard Id or a free-form String for use by a non-Blackboard assessment handler.

To link to an external assessment engine, you must also call #setAttemptHandlerUrl(). The gradebook rendering logic will display the scores with a link to that URL, passing this id as a parameter.

Note: calling this method will clear the internal assessment ID, if there is one, currently associated with this Lineitem.

Parameters:

id - The Id of the assessment this Lineitem is derived from.

clearAssessmentId

protected void clearAssessmentId()

Clears the assessmentId and sets assessmentLocation to UNSET.

getAssessmentLocation

public Lineitem.AssessmentLocation getAssessmentLocation()

assessmentLocation indicates whether the assessment referenced by this Lineitem is native to the Blackboard server or stored externally. It may be implied by other properties:

• If the underlying OutcomeDefinition object's asiDataId attribute is set, assessmentLocation is Lineitem.AssessmentLocation.INTERNAL
• If the underlying OutcomeDefinition object's linkId attribute is set, assessmentLocation is Lineitem.AssessmentLocation.EXTERNAL
• If neither is set, assessmentLocation is Lineitem.AssessmentLocation.UNSET

This value should typically only be of interest if the Lineitem points to an external assessment engine. It is then set implicitly via #setExternalAssessmentId().

Returns:

Value of field, based on above rules.

setAssessmentLocation

public void setAssessmentLocation(Lineitem.AssessmentLocation assessmentLocation)

Manual over-ride for assessmentLocation. This method should not be called directly.

Parameters:

assessmentLocation - Value to set.

getName

public java.lang.String getName()

Returns the name of the Lineitem. This will correspond to the column header in the spreadsheet view.

Returns:

The name of the Lineitem

setName

public void setName(java.lang.String strName)

Sets the name of the Lineitem.

Parameters:

strName - The name of the Lineitem

getType

public java.lang.String getType()

Returns the type of the Lineitem, for example 'Assessment' or 'Homework'. This value is actually free-form, even though a drop-down appears in the user interface.

Returns:

The type of the Lineitem

setType

public void setType(java.lang.String strType)
             throws java.lang.IllegalArgumentException

Sets the type of the Lineitem. The type does not have to conform to a preset list. However, if the type does not exist in association with the current course, it is written to the database.

Parameters:

strType - The type of the Lineitem, as a String. The value does not have to conform to a preset list.

Throws:

java.lang.IllegalArgumentException

getIsAvailable

public boolean getIsAvailable()

Returns a flag describing whether students can see the item in their views of the gradebook.

Specified by:

getIsAvailable in interface Available

Returns:

True if the Lineitem is visible to the student, false otherwise

setIsAvailable

public void setIsAvailable(boolean bIsAvailable)

Sets a flag describing whether students can see the item in their views of the gradebook.

Specified by:

setIsAvailable in interface Available

Parameters:

bIsAvailable - True if the Lineitem should be visible to the student, false otherwise

getColumnOrder

public int getColumnOrder()

Returns the column position for this line item.

Returns:

Column position for this line item.

setColumnOrder

public void setColumnOrder(int iColumnOrder)

getPointsPossible

public float getPointsPossible()

Gets the points possible for this Lineitem

Returns:

Points possible, as a float value

setPointsPossible

public void setPointsPossible(float fPointsPossible)

Sets the maximum points possible for this Lineitem.

Parameters:

fPointsPossible - Float value for points possible.

getWeight

public float getWeight()

Gets the weight used in calculating cumulative scores.

Returns:

setWeight

public void setWeight(float fWeight)

Sets the weight (as a percentage) for this Lineitem. Thus, if you wanted to weight this lineitem as 40% of the total, you should set this value to .40F.

Parameters:

fWeight - Percentage weight as a float value.

getAttemptHandlerUrl

public java.lang.String getAttemptHandlerUrl()

Returns the URL for this item's attemptHandler if this Lineitem points to an external assessment.

Note that in release 5.x, the URL format for the system extension did not include the Virtual Installation information; in release 6.x, the URL includes a string in the URL that does identify the Virtual Installation. As a result, developers should double check the value to make sure it is in the proper format.

Returns:

The URL for the external attempt handler.

setAttemptHandlerUrl

public void setAttemptHandlerUrl(java.lang.String attemptHandlerUrl)

Sets the URL to render student attempt data, if this Lineitem is set to interact with external assessment engines.

Note that in release 5.x, the URL format for the system extension did not include the Virtual Installation information; in release 6.x, the URL includes a string in the URL that does identify the Virtual Installation. As a result, developers should double check the value to make sure it is in the proper format.

Parameters:

attemptHandlerUrl - URL value.

getAnalysisHandlerUrl

public java.lang.String getAnalysisHandlerUrl()

setAnalysisHandlerUrl

public void setAnalysisHandlerUrl(java.lang.String analysisHandlerUrl)

getDateAdded

public java.util.Calendar getDateAdded()

Returns the date and time this Score was added to the gradebook. This field is separate from the database row specific timestamp for creation, which simply tags the time the row was inserted.

Returns:

A Calendar containing the date and time when this Lineitem was added to the gradebook

setDateAdded

public void setDateAdded()

Sets the date and time this Lineitem was added to the gradebook using the current time. This field is separate from the database row specific timestamp for creation, which simply tags the time the row was inserted.

setDateAdded

public void setDateAdded(java.util.Calendar cDateAdded)

Sets the date and time this Lineitem was added to the gradebook using the provided Calendar. This field is separate from the database row specific timestamp for creation, which simply tags the time the row was inserted.

Parameters:

cDateAdded - The date and time this Lineitem was added to the gradebook

getDateChanged

public java.util.Calendar getDateChanged()

Returns the date and time this Lineitem was modified. This field is separate from the database row specific timestamp for modification, which simply tags the time the row was updated.

Returns:

A Calendar containing the date and time when this Lineitem was modified

setDateChanged

public void setDateChanged()

Sets the date and time this Lineitem was modified using the current time. This field is separate from the database row specific timestamp for creation, which simply tags the time the row was updated.

setDateChanged

public void setDateChanged(java.util.Calendar cDateChanged)

Sets the date and time this Lineitem was modified using the provided Calendar. This field is separate from the database row specific timestamp for creation, which simply tags the time the row was updated.

Parameters:

cDateChanged - The date and time this Lineitem was modified

getScores

public BbList getScores()

Gets all scores associated with this LineItem.

Returns:

The list of Scores associated with this LineItem.

setScores

public void setScores(BbList scores)

Associates the input Score objects to this LineItem object. The LineItem must be persisted before invoking this method. The scores are not persisted when this LineItem is persisted. The client must explicitly persist each Score.

Parameters:

scores - - List of Score objects

getDataType

public DataType getDataType()

Returns the DataType identifier for this object. Can be used to uniquely identify the "type" of this data object.

Specified by:

getDataType in interface IBbObject

Specified by:

getDataType in class BbObject

Returns:

the DataType for this object

toString

public java.lang.String toString()

Returns the contents of this Lineitem object as a line-feed separated list of name value pairs of this object's properties. The line-feed character used is the one specified by the java system property "line.separator". This method can be used for debug purposes.

Overrides:

toString in class BbObject

Returns:

a String that represents the contents of this object

validate

public void validate()
              throws ValidationException

Validates the contents of this LineItem. Internal consistency checks are also performed.

Specified by:

validate in interface IBbObject

Overrides:

validate in class BbObject

Throws:

ValidationException - if validation of this object fails