Package edu.internet2.middleware.subject.provider

Class BaseSourceAdapter

java.lang.Object

edu.internet2.middleware.subject.provider.BaseSourceAdapter

All Implemented Interfaces:

Source

Direct Known Subclasses:

GrouperSourceAdapter, InternalSourceAdapter, JDBCSourceAdapter, JNDISourceAdapterLegacy, LdapSourceAdapter, NullSourceAdapter

public abstract class BaseSourceAdapter
extends Object
implements Source

 Base Source adapter.
 
 Developers note: you should implement the getSubject and getSubjectByIdentifier
 methods (that take boolean) since the base class method will soon become abstract, and the
 method overloads which are deprecated and dont take booleans will go away.
 
 

Field Summary

Fields

Modifier and Type	Field	Description
protected Set<String>	attributes
protected String	descriptionAttributeName
protected String	id
protected Set<String>	internalAttributes	internal attributes.
protected String	name
protected String	nameAttributeName
protected Properties	params
protected Map<Integer,String>	searchAttributes
protected HashMap<String,Search>	searches	The three different kinds of searches:
protected Map<Integer,String>	sortAttributes
protected Map<Integer,String>	subjectIdentifierAttributes
protected Map<Integer,String>	subjectIdentifierAttributesAll
protected SubjectType	type
protected Set<SubjectType>	types

Constructor Summary

Constructors

Constructor	Description
BaseSourceAdapter()	Default constructor.
BaseSourceAdapter(String id1, String name1)	Allocates adapter with ID and name.

Method Summary

Modifier and Type	Method	Description
void	addAttribute(String attributeName)
void	addInitParam(String name1, String value)	(non-javadoc)
void	addInternalAttribute(String attributeName)
void	addSubjectType(String type1)	(non-javadoc)
Map<String,String>	attributeNameToViewerGroupName()	return the attribute name
String	convertSourceAttributeToSubjectAttribute(String nameOfSourceAttribute)
String	convertSubjectAttributeToSourceAttribute(String nameOfSubjectAttribute)
protected Subject	createSubject(Map<String,Object> sourceAttributesToValues, String subjectID)
boolean	equals(Object other)	Compares this source against the specified source.
Map<String,String>	exportLabelToAttributeName()	return export label to attribute name (if there are overrides)
protected Set	getAttributes()
String	getConfigId()
String	getId()	Returns the ID of this source.
String	getInitParam(String name1)	(non-javadoc)
Set<String>	getInternalAttributes()	Get a set of attributes that are marked as being internal attributes.
String	getName()	Returns the name of this source.
protected Search	getSearch(String searchType)
Map<Integer,String>	getSearchAttributes()	Get the names of attributes used for searching.
protected HashMap<String,Search>	getSearches()
Map<Integer,String>	getSortAttributes()	Get the names of attributes used for sorting.
Set<String>	getSourceAttributesToLowerCase()
abstract Subject	getSubject(String id1)	Deprecated. use the overload instead
Subject	getSubject(String id1, boolean exceptionIfNull)	Gets a Subject by its ID.
Subject	getSubject(String id1, boolean exceptionIfNull, String realm)	Gets a Subject by its ID.
abstract Subject	getSubjectByIdentifier(String id1)	Deprecated. use the overload instead
Subject	getSubjectByIdentifier(String id1, boolean exceptionIfNull)	note, you should implement this method since this implementation will become abstract at some point
Subject	getSubjectByIdentifier(String id1, boolean exceptionIfNull, String realm)	Gets a Subject by other well-known identifiers, aside from the subject ID, for example, login ID.
Subject	getSubjectByIdOrIdentifier(String idOrIdentifier, boolean exceptionIfNull)	find by id or identifier
Subject	getSubjectByIdOrIdentifier(String idOrIdentifier, boolean exceptionIfNull, String realm)	find by id or identifier.
Map<Integer,String>	getSubjectIdentifierAttributes()	Get the names of attributes that are subject identifiers.
Map<Integer,String>	getSubjectIdentifierAttributesAll()	Get all the names of attributes that are subject identifiers.
Map<String,Subject>	getSubjectsByIdentifiers(Collection<String> identifiers)	Get subjects by identifiers.
Map<String,Subject>	getSubjectsByIdentifiers(Collection<String> identifiers, String realm)	Get subjects by identifiers.
Map<String,Subject>	getSubjectsByIds(Collection<String> ids)	Get subjects by ids.
Map<String,Subject>	getSubjectsByIds(Collection<String> ids, String realm)	Get subjects by ids.
Map<String,Subject>	getSubjectsByIdsOrIdentifiers(Collection<String> idsOrIdentifiers)	Get subjects by ids or identifiers.
Map<String,Subject>	getSubjectsByIdsOrIdentifiers(Collection<String> idsOrIdentifiers, String realm)	Get subjects by ids or identifiers.
SubjectStatusConfig	getSubjectStatusConfig()	get the config bean for this source
SubjectType	getSubjectType()
Set<SubjectType>	getSubjectTypes()	Gets the SubjectTypes supported by this source.
int	hashCode()
abstract void	init()	Called by SourceManager when it loads this source.
Properties	initParams()	(non-javadoc)
boolean	isEditable()
boolean	isEnabled()
void	loadSearch(Search search)
void	removeInitParam(String name1)
static Integer	resultSetLimit(boolean firstPageOnly, Integer pageSize, Integer theMaxResults)	see what the result set limit should be (dont add one yet)
Set<String>	retrieveAllSubjectIds()	get all subject ids
abstract Set<Subject>	search(String searchValue)	Unstructured search for Subjects.
Set<Subject>	search(String searchValue, String realm)	Unstructured search for Subjects.
SearchPageResult	searchPage(String searchValue)	Unstructured search for Subjects.
SearchPageResult	searchPage(String searchValue, String realm)	Unstructured search for Subjects.
void	setConfigId(String configId)	set config id for this source
void	setId(String id1)	Sets the ID of this source.
void	setName(String name1)	Sets the name of this source.
void	setSearchAttributes(Map<Integer,String> searchAttributes)
protected void	setSearches(HashMap<String,Search> searches1)
void	setSortAttributes(Map<Integer,String> sortAttributes)
void	setSubjectIdentifierAttributes(Map<Integer,String> subjectIdentifierAttributes)
void	setSubjectIdentifierAttributesAll(Map<Integer,String> subjectIdentifierAttributesAll)
static Map<String,String>	virtualAttributesForSource(Source source)	get the ordered list of virtual attributes for a source (new style)
static Map<String,String>	virtualAttributesForSourceLegacy(Source source)	get the ordered list of virtual attributes for a source
static Map<String,String>	virtualAttributeVariablesForSourceLegacy(Source source)	get the ordered list of virtual attributes for a source

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface edu.internet2.middleware.subject.Source

checkConfig, loggingStart, loggingStop, printConfig

Field Details

nameAttributeName

protected String nameAttributeName

descriptionAttributeName

protected String descriptionAttributeName

id

protected String id

name

protected String name

types

protected Set<SubjectType> types

type

protected SubjectType type

params

protected Properties params

searches

protected HashMap<String,Search> searches

The three different kinds of searches:

attributes

protected Set<String> attributes

internalAttributes

protected Set<String> internalAttributes

internal attributes.

subjectIdentifierAttributes

protected Map<Integer,String> subjectIdentifierAttributes

subjectIdentifierAttributesAll

protected Map<Integer,String> subjectIdentifierAttributesAll

sortAttributes

protected Map<Integer,String> sortAttributes

searchAttributes

protected Map<Integer,String> searchAttributes

Constructor Details

BaseSourceAdapter

public BaseSourceAdapter()

Default constructor.

BaseSourceAdapter

public BaseSourceAdapter(String id1,
 String name1)

Allocates adapter with ID and name.

Parameters:

id1 -

name1 -

Method Details

createSubject

protected Subject createSubject(Map<String,Object> sourceAttributesToValues,
 String subjectID)

getSourceAttributesToLowerCase

public Set<String> getSourceAttributesToLowerCase()

convertSubjectAttributeToSourceAttribute

public String convertSubjectAttributeToSourceAttribute(String nameOfSubjectAttribute)

Specified by:

convertSubjectAttributeToSourceAttribute in interface Source

exportLabelToAttributeName

public Map<String,String> exportLabelToAttributeName()

return export label to attribute name (if there are overrides)

Returns:

empty if no overrides, otherwise the attribute name to export label

attributeNameToViewerGroupName

public Map<String,String> attributeNameToViewerGroupName()

return the attribute name

Returns:

empty if no overrides, otherwise the attribute name to export label

convertSourceAttributeToSubjectAttribute

public String convertSourceAttributeToSubjectAttribute(String nameOfSourceAttribute)

Specified by:

convertSourceAttributeToSubjectAttribute in interface Source

retrieveAllSubjectIds

public Set<String> retrieveAllSubjectIds()

Description copied from interface: Source

get all subject ids

Specified by:

retrieveAllSubjectIds in interface Source

Returns:

all subjectIds

See Also:

• Source.retrieveAllSubjectIds()

getSubject

public Subject getSubject(String id1,
 boolean exceptionIfNull,
 String realm)
                   throws SubjectNotFoundException,
SubjectNotUniqueException

Description copied from interface: Source

Gets a Subject by its ID.

Specified by:

getSubject in interface Source

exceptionIfNull - if SubjectNotFoundException should be throws if the subject is null, or if null should be returned

realm - string value that sets the realm for the search. The source can implement various realms to account for permissions of the calling user

Returns:

subject

Throws:

SubjectNotFoundException

SubjectNotUniqueException

See Also:

• Source.getSubject(java.lang.String, boolean, java.lang.String)

getSubjectByIdentifier

public Subject getSubjectByIdentifier(String id1,
 boolean exceptionIfNull,
 String realm)
                               throws SubjectNotFoundException,
SubjectNotUniqueException

Description copied from interface: Source

Gets a Subject by other well-known identifiers, aside from the subject ID, for example, login ID.

Specified by:

getSubjectByIdentifier in interface Source

realm - string value that sets the realm for the search. The source can implement various realms to account for permissions of the calling user

Returns:

subject

Throws:

SubjectNotFoundException

SubjectNotUniqueException

See Also:

• Source.getSubjectByIdentifier(java.lang.String, boolean, java.lang.String)

getSubjectByIdOrIdentifier

public Subject getSubjectByIdOrIdentifier(String idOrIdentifier,
 boolean exceptionIfNull,
 String realm)
                                   throws SubjectNotFoundException,
SubjectNotUniqueException

Description copied from interface: Source

find by id or identifier. pass in either an id or an identifier

Specified by:

getSubjectByIdOrIdentifier in interface Source

exceptionIfNull - if SubjectNotFoundException or null

realm - string value that sets the realm for the search. The source can implement various realms to account for permissions of the calling user

Returns:

the subject

Throws:

SubjectNotFoundException

SubjectNotUniqueException

See Also:

• Source.getSubjectByIdOrIdentifier(java.lang.String, boolean, java.lang.String)

getSubjectsByIdentifiers

public Map<String,Subject> getSubjectsByIdentifiers(Collection<String> identifiers,
 String realm)

Description copied from interface: Source

Get subjects by identifiers. Note, if the subjects arent found or arent unique, they wont be returned. Identifiers are unique ways to refer to a subject that isnt its id (e.g. netid). Duplicates are ok on the input, but will return one output.

Specified by:

getSubjectsByIdentifiers in interface Source

realm - string value that sets the realm for the search. The source can implement various realms to account for permissions of the calling user

Returns:

a map of results never null indexed by the identifiers

See Also:

• Source.getSubjectsByIdentifiers(java.util.Collection, java.lang.String)

getSubjectsByIds

public Map<String,Subject> getSubjectsByIds(Collection<String> ids,
 String realm)

Description copied from interface: Source

Get subjects by ids. Note, if the subjects arent found or arent unique, they wont be returned. Duplicates are ok on the input, but will return one output.

Specified by:

getSubjectsByIds in interface Source

realm - string value that sets the realm for the search. The source can implement various realms to account for permissions of the calling user

Returns:

a map of results never null indexed by the id

See Also:

• Source.getSubjectsByIds(java.util.Collection, java.lang.String)

getSubjectsByIdsOrIdentifiers

public Map<String,Subject> getSubjectsByIdsOrIdentifiers(Collection<String> idsOrIdentifiers,
 String realm)

Description copied from interface: Source

Get subjects by ids or identifiers. Note, if the subjects arent found or arent unique, they wont be returned. Identifiers are unique ways to refer to a subject that isnt its id (e.g. netid). Duplicates are ok on the input, but will return one output.

Specified by:

getSubjectsByIdsOrIdentifiers in interface Source

Parameters:

idsOrIdentifiers - each string could be a subject id or identifier

realm - string value that sets the realm for the search. The source can implement various realms to account for permissions of the calling user

Returns:

a map of results never null indexed by the id or identifier that was passed in. Note, the same subject could be returned twice if looked up by id and identifier (two inputs)

See Also:

• Source.getSubjectsByIdsOrIdentifiers(java.util.Collection, java.lang.String)

search

public Set<Subject> search(String searchValue,
 String realm)

Description copied from interface: Source

Unstructured search for Subjects. Each implementation utilizes its own search algorithm tailored to the Subject repository and schema. Note if config param: throwErrorOnFindAllFailure is false, then swallow and log exceptions

Specified by:

search in interface Source

realm - string value that sets the realm for the search. The source can implement various realms to account for permissions of the calling user

Returns:

set

See Also:

• Source.search(java.lang.String, java.lang.String)

searchPage

public SearchPageResult searchPage(String searchValue,
 String realm)

Description copied from interface: Source

Unstructured search for Subjects. Each implementation utilizes its own search algorithm tailored to the Subject repository and schema. Note if config param: throwErrorOnFindAllFailure is false, then swallow and log exceptions if maxPageSize is set in subject.properties, then only return max that many, and if there are more, set the tooManyResults flag

Specified by:

searchPage in interface Source

realm - string value that sets the realm for the search. The source can implement various realms to account for permissions of the calling user

Returns:

results and if there are too many, never return null!!!

See Also:

• Source.searchPage(java.lang.String, java.lang.String)

getSubjectStatusConfig

public SubjectStatusConfig getSubjectStatusConfig()

Description copied from interface: Source

get the config bean for this source

Specified by:

getSubjectStatusConfig in interface Source

Returns:

the config bean for this source

See Also:

• Source.getSubjectStatusConfig()

resultSetLimit

public static Integer resultSetLimit(boolean firstPageOnly,
 Integer pageSize,
 Integer theMaxResults)

see what the result set limit should be (dont add one yet)

Parameters:

firstPageOnly -

pageSize -

theMaxResults -

Returns:

the limit or null if none

searchPage

public SearchPageResult searchPage(String searchValue)

Description copied from interface: Source

Unstructured search for Subjects. Each implementation utilizes its own search algorithm tailored to the Subject repository and schema. Note if config param: throwErrorOnFindAllFailure is false, then swallow and log exceptions if maxPageSize is set in subject.properties, then only return max that many, and if there are more, set the tooManyResults flag

Specified by:

searchPage in interface Source

Returns:

results and if there are too many, never return null!!!

See Also:

• Source.searchPage(java.lang.String)

getSubjectsByIdentifiers

public Map<String,Subject> getSubjectsByIdentifiers(Collection<String> identifiers)

Description copied from interface: Source

Get subjects by identifiers. Note, if the subjects arent found or arent unique, they wont be returned. Identifiers are unique ways to refer to a subject that isnt its id (e.g. netid). Duplicates are ok on the input, but will return one output.

Specified by:

getSubjectsByIdentifiers in interface Source

Returns:

a map of results never null indexed by the identifiers

See Also:

• Source.getSubjectsByIdentifiers(java.util.Collection)

getSubjectsByIds

public Map<String,Subject> getSubjectsByIds(Collection<String> ids)

Description copied from interface: Source

Get subjects by ids. Note, if the subjects arent found or arent unique, they wont be returned. Duplicates are ok on the input, but will return one output.

Specified by:

getSubjectsByIds in interface Source

Returns:

a map of results never null indexed by the id

See Also:

• Source.getSubjectsByIds(java.util.Collection)

getSubjectByIdOrIdentifier

public Subject getSubjectByIdOrIdentifier(String idOrIdentifier,
 boolean exceptionIfNull)
                                   throws SubjectNotFoundException,
SubjectNotUniqueException

find by id or identifier

Specified by:

getSubjectByIdOrIdentifier in interface Source

Parameters:

idOrIdentifier -

exceptionIfNull - if SubjectNotFoundException or null

Returns:

the subject

Throws:

SubjectNotFoundException

SubjectNotUniqueException

getSubjectsByIdsOrIdentifiers

public Map<String,Subject> getSubjectsByIdsOrIdentifiers(Collection<String> idsOrIdentifiers)

Description copied from interface: Source

Get subjects by ids or identifiers. Note, if the subjects arent found or arent unique, they wont be returned. Identifiers are unique ways to refer to a subject that isnt its id (e.g. netid). Duplicates are ok on the input, but will return one output.

Specified by:

getSubjectsByIdsOrIdentifiers in interface Source

Parameters:

idsOrIdentifiers - each string could be a subject id or identifier

Returns:

a map of results never null indexed by the id or identifier that was passed in. Note, the same subject could be returned twice if looked up by id and identifier (two inputs)

See Also:

• Source.getSubjectsByIdsOrIdentifiers(java.util.Collection)

getId

public String getId()

Returns the ID of this source.

Specified by:

getId in interface Source

Returns:

id

setId

public void setId(String id1)

Sets the ID of this source.

Specified by:

setId in interface Source

getName

public String getName()

Returns the name of this source.

Specified by:

getName in interface Source

Returns:

name

setName

public void setName(String name1)

Sets the name of this source.

Specified by:

setName in interface Source

getSubjectTypes

public Set<SubjectType> getSubjectTypes()

Gets the SubjectTypes supported by this source.

Specified by:

getSubjectTypes in interface Source

Returns:

set

getSubjectType

public SubjectType getSubjectType()

Returns:

subject type

getSubject

@Deprecated
public abstract Subject getSubject(String id1)
                            throws SubjectNotFoundException,
SubjectNotUniqueException

Deprecated.

use the overload instead

Description copied from interface: Source

Gets a Subject by its ID.

Specified by:

getSubject in interface Source

Returns:

subject

Throws:

SubjectNotFoundException

SubjectNotUniqueException

See Also:

• Source.getSubject(java.lang.String)

getSubject

public Subject getSubject(String id1,
 boolean exceptionIfNull)
                   throws SubjectNotFoundException,
SubjectNotUniqueException

Description copied from interface: Source

Gets a Subject by its ID.

Specified by:

getSubject in interface Source

exceptionIfNull - if SubjectNotFoundException should be throws if the subject is null, or if null should be returned

Returns:

subject

Throws:

SubjectNotFoundException

SubjectNotUniqueException

See Also:

• Source.getSubject(java.lang.String, boolean)

getSubjectByIdentifier

@Deprecated
public abstract Subject getSubjectByIdentifier(String id1)
                                        throws SubjectNotFoundException,
SubjectNotUniqueException

Deprecated.

use the overload instead

Description copied from interface: Source

Gets a Subject by other well-known identifiers, aside from the subject ID, for example, login ID.

Specified by:

getSubjectByIdentifier in interface Source

Returns:

subject

Throws:

SubjectNotFoundException

SubjectNotUniqueException

See Also:

• Source.getSubjectByIdentifier(java.lang.String)

getSubjectByIdentifier

public Subject getSubjectByIdentifier(String id1,
 boolean exceptionIfNull)
                               throws SubjectNotFoundException,
SubjectNotUniqueException

note, you should implement this method since this implementation will become abstract at some point

Specified by:

getSubjectByIdentifier in interface Source

Returns:

subject

Throws:

SubjectNotFoundException

SubjectNotUniqueException

See Also:

• Source.getSubjectByIdentifier(java.lang.String, boolean)

search

public abstract Set<Subject> search(String searchValue)

Unstructured search for Subjects. Each implementation utilizes its own search algorithm tailored to the Subject repository and schema. Note if config param: throwErrorOnFindAllFailure is false, then swallow and log exceptions

Specified by:

search in interface Source

Returns:

set

init

public abstract void init()
                   throws SourceUnavailableException

Called by SourceManager when it loads this source.

Specified by:

init in interface Source

Throws:

SourceUnavailableException

equals

public boolean equals(Object other)

Compares this source against the specified source. Returns true if the IDs of both sources are equal.

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

See Also:

• Object.hashCode()

addSubjectType

public void addSubjectType(String type1)

(non-javadoc)

Parameters:

type1 -

addInitParam

public void addInitParam(String name1,
 String value)

(non-javadoc)

Parameters:

name1 -

value -

removeInitParam

public void removeInitParam(String name1)

Parameters:

name1 -

getInitParam

public String getInitParam(String name1)

(non-javadoc)

Specified by:

getInitParam in interface Source

Parameters:

name1 -

Returns:

param

initParams

public Properties initParams()

(non-javadoc)

Specified by:

initParams in interface Source

Returns:

params

addAttribute

public void addAttribute(String attributeName)

Parameters:

attributeName -

addInternalAttribute

public void addInternalAttribute(String attributeName)

Parameters:

attributeName -

getAttributes

protected Set getAttributes()

Returns:

set

getInternalAttributes

public Set<String> getInternalAttributes()

Description copied from interface: Source

Get a set of attributes that are marked as being internal attributes. Note, these will be in lower case

Specified by:

getInternalAttributes in interface Source

Returns:

set

setSearches

protected void setSearches(HashMap<String,Search> searches1)

Parameters:

searches1 -

getSearches

protected HashMap<String,Search> getSearches()

Returns:

map

getSearch

protected Search getSearch(String searchType)

Parameters:

searchType -

Returns:

search

loadSearch

public void loadSearch(Search search)

Parameters:

search -

setSubjectIdentifierAttributes

public void setSubjectIdentifierAttributes(Map<Integer,String> subjectIdentifierAttributes)

Parameters:

subjectIdentifierAttributes -

setSubjectIdentifierAttributesAll

public void setSubjectIdentifierAttributesAll(Map<Integer,String> subjectIdentifierAttributesAll)

Parameters:

subjectIdentifierAttributesAll -

setSortAttributes

public void setSortAttributes(Map<Integer,String> sortAttributes)

Parameters:

sortAttributes -

setSearchAttributes

public void setSearchAttributes(Map<Integer,String> searchAttributes)

Parameters:

searchAttributes -

getSubjectIdentifierAttributes

public Map<Integer,String> getSubjectIdentifierAttributes()

Description copied from interface: Source

Get the names of attributes that are subject identifiers. This only returns the first

Specified by:

getSubjectIdentifierAttributes in interface Source

Returns:

subject identifiers

See Also:

• Source.getSubjectIdentifierAttributes()

getSubjectIdentifierAttributesAll

public Map<Integer,String> getSubjectIdentifierAttributesAll()

Description copied from interface: Source

Get all the names of attributes that are subject identifiers.

Specified by:

getSubjectIdentifierAttributesAll in interface Source

Returns:

subject identifiers

See Also:

• Source.getSubjectIdentifierAttributesAll()

getSortAttributes

public Map<Integer,String> getSortAttributes()

Description copied from interface: Source

Get the names of attributes used for sorting.

Specified by:

getSortAttributes in interface Source

Returns:

sort attributes in lower case

See Also:

• Source.getSortAttributes()

getSearchAttributes

public Map<Integer,String> getSearchAttributes()

Description copied from interface: Source

Get the names of attributes used for searching.

Specified by:

getSearchAttributes in interface Source

Returns:

search attributes in lower case

See Also:

• Source.getSearchAttributes()

isEditable

public boolean isEditable()

Specified by:

isEditable in interface Source

Returns:

true if the source is editable otherwise false

getConfigId

public String getConfigId()

Specified by:

getConfigId in interface Source

Returns:

configId for this source

setConfigId

public void setConfigId(String configId)

Description copied from interface: Source

set config id for this source

Specified by:

setConfigId in interface Source

isEnabled

public boolean isEnabled()

Specified by:

isEnabled in interface Source

Returns:

true if the source is active otherwise false

virtualAttributesForSource

public static Map<String,String> virtualAttributesForSource(Source source)

get the ordered list of virtual attributes for a source (new style)

Parameters:

source -

Returns:

the ordered list

virtualAttributesForSourceLegacy

public static Map<String,String> virtualAttributesForSourceLegacy(Source source)

get the ordered list of virtual attributes for a source

Parameters:

source -

Returns:

the ordered list

virtualAttributeVariablesForSourceLegacy

public static Map<String,String> virtualAttributeVariablesForSourceLegacy(Source source)

get the ordered list of virtual attributes for a source

Parameters:

source -

Returns:

the ordered list