org.pajes.db.entity
Class Lister

java.lang.Object
  org.pajes.db.entity.MaintenanceDisplayElement
      org.pajes.db.entity.Lister

All Implemented Interfaces:

java.lang.Cloneable

Direct Known Subclasses:

PagingLister

public abstract class Lister

extends MaintenanceDisplayElement

Abstract super-class of all classes that create a Paje with a list of Entity objects.

All sub-classes MUST have a no-parameter constructor.

Field Summary

static java.lang.String	SEARCH_ATTRIBUTE_SUFFIX The suffix appended to the Manager class name to create the name of the HttpSession attribute that contains the current search/filter Scope.
static java.lang.String	SEARCH_PARAMETER The name of the request parameter that determines whether the result set is to be filtered on other request parameters.
static java.lang.String	SEARCH_PARAMETER_VALUE The value of the SEARCH_PARAMETER request parameter that indicates that the result set is to be filtered on other request parameters.
static java.lang.String	SORT_ATTRIBUTE_SUFFIX The suffix appended to the Manager class name to create the name of the HttpSession attribute that contains the name of the current sort column.
static java.lang.String	SORT_PARAMETER The name of the request parameter that determines the column on which the list will be sorted.

Constructor Summary

Lister()

Method Summary

protected void	build() Retrieves the required Entity objects specified by the scope, and adds them to the Table which is the parent of the row(s) returned by getRow(int).
protected Anchor	getAnchor(Entity entity) Returns the Anchor that will dictate where the user is sent to when they select an object from the list.
protected abstract Anchor	getBaseAnchor() Returns the base Anchor used by {#link #getAnchor}.
protected abstract int	getHeaderRowCount() Returns the number of header rows.
abstract Paje	getPaje() Returns the Paje containing the list of Entity objects.
protected abstract Table.Row	getRow(int rowNumber) Returns the row to be populated from an Entity.
protected Scope	getScope() Returns the Scope that will limit the list of Entity objects displayed, and the order in which they are displayed.
protected java.lang.String	getSearchAttributeName() Returns the name of the HttpSession attribute that contains the current search scope.
protected java.lang.String	getSortAttributeName() Returns the name of the HttpSession attribute that contains the current sort column.
void	init(Manager manager, javax.servlet.ServletContext context) Initialises the Lister.
void	init(Manager manager, javax.servlet.ServletContext context, javax.servlet.http.HttpServletRequest request) Deprecated. 2.1.1 - use init(Manager, ServletContext) and setRequest(HttpServletRequest).
protected void	onCell(int rowNumber, Table.Cell cell, Entity entity) Called immediately after the cell has been processed, even if no Anchor was added to the cell.
protected void	onFirstRow(Table.Row row, Entity entity) Called immediately after the first row has been added to the list table, but before the onRow(int, org.pajes.html.Table.Row, org.pajes.db.entity.Entity) method for the first row.
protected void	onLastRow(int rowNumber, Table.Row row, Entity entity) Called after the last row has been added to the list table, and after the onRow(int, org.pajes.html.Table.Row, org.pajes.db.entity.Entity) method for the last row.
protected void	onRow(int rowNumber, Table.Row row, Entity entity) Called immediately after the row has been added to the list table.
protected Entity[]	retrieveSet() Returns the set of Entity objects to be displayed in the list.
protected void	setNullDisplay(java.lang.String display) Sets the String that will be displayed if a column value in an Entity has a null value.
protected void	useQualifiedColumnNamesInScope(boolean on) Determines whether column names should be qualified with the table name when building the scope.

Methods inherited from class org.pajes.db.entity.MaintenanceDisplayElement

clone, getManager, getRequest, getServletContext, init, isInitialised, setRequest

Methods inherited from class java.lang.Object

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

Field Detail

SEARCH_PARAMETER

public static final java.lang.String SEARCH_PARAMETER

The name of the request parameter that determines whether the result set is to be filtered on other request parameters.

See Also:

Constant Field Values

SEARCH_PARAMETER_VALUE

public static final java.lang.String SEARCH_PARAMETER_VALUE

The value of the SEARCH_PARAMETER request parameter that indicates that the result set is to be filtered on other request parameters. Any other value means that the result is NOT to be filtered.

See Also:

Constant Field Values

SEARCH_ATTRIBUTE_SUFFIX

public static final java.lang.String SEARCH_ATTRIBUTE_SUFFIX

The suffix appended to the Manager class name to create the name of the HttpSession attribute that contains the current search/filter Scope.

See Also:

getSearchAttributeName(), Constant Field Values

SORT_ATTRIBUTE_SUFFIX

public static final java.lang.String SORT_ATTRIBUTE_SUFFIX

The suffix appended to the Manager class name to create the name of the HttpSession attribute that contains the name of the current sort column.

See Also:

getSortAttributeName(), Constant Field Values

SORT_PARAMETER

public static final java.lang.String SORT_PARAMETER

The name of the request parameter that determines the column on which the list will be sorted.

See Also:

Constant Field Values

Constructor Detail

Lister

public Lister()

Method Detail

getPaje

public abstract Paje getPaje()
                      throws java.io.IOException

Returns the Paje containing the list of Entity objects.

Sub-class implementations should build or acquire a Paje instance (either by building the Paje on the fly, or creating one from a PajeFactory), make the table rows on the Paje accessible via getRow(int), and then call the build() method to populate the cells.

Returns:

the populated Paje.

Throws:

java.io.IOException - if an IO exception occurs.

See Also:

build()

init

public void init(Manager manager,
                 javax.servlet.ServletContext context,
                 javax.servlet.http.HttpServletRequest request)
          throws EntityNotFoundException,
                 java.io.IOException,
                 java.sql.SQLException

Deprecated. 2.1.1 - use init(Manager, ServletContext) and setRequest(HttpServletRequest).

Deprecated.

Parameters:

manager - the Manager that manages the Entity objects to be listed.

context - the ServletContext.

request - the request object.

Throws:

EntityNotFoundException - if the Entity to be edited does not exist.

java.io.IOException - if an IO exception occurs.

java.sql.SQLException - if an error occurs retrieving the Entity objects.

init

public void init(Manager manager,
                 javax.servlet.ServletContext context)
          throws java.io.IOException

Initialises the Lister.

Sub-classes should not over-ride this method. Instead, sub-classes should over-ride the MaintenanceDisplayElement.init() method, which is called automatically by this method. If this method is over-rdden, the sub-class MUST call super.init(manager, context, request) to correctly iniitalise the lister.

Overrides:

init in class MaintenanceDisplayElement

Parameters:

manager - the Manager that manages the Entity objects to be listed.

context - the ServletContext.

Throws:

java.io.IOException - if an IO exception occurs.

useQualifiedColumnNamesInScope

protected void useQualifiedColumnNamesInScope(boolean on)

Determines whether column names should be qualified with the table name when building the scope.

Parameters:

on - true if column names should be qualified with the table name when building the scope.

getAnchor

protected Anchor getAnchor(Entity entity)

Returns the Anchor that will dictate where the user is sent to when they select an object from the list.

This implementation returns the Anchor retrieved from getBaseAnchor() with the primary keys of the specified Entity added as parameters.

The returned Anchor will be cloned to create Anchor objects for each column in the table row.

Sub-classes may over-ride this method to return an Anchor other than the default.

Parameters:

entity - the entity to which this Anchor will relate.

Returns:

the Anchor.

getBaseAnchor

protected abstract Anchor getBaseAnchor()

Returns the base Anchor used by {#link #getAnchor}.

Returns:

the Anchor.

getHeaderRowCount

protected abstract int getHeaderRowCount()

Returns the number of header rows.

Returns:

the number of header rows.

getRow

protected abstract Table.Row getRow(int rowNumber)

Returns the row to be populated from an Entity.

Note that this method should return a new instance with each invocation, either by direct creation or by cloning. Under no circumstances should one instance be returned mulitple times.

Parameters:

rowNumber - the position in the list of the required row. Note that the first position in the list is rowNumber 1.

Returns:

The row value.

setNullDisplay

protected void setNullDisplay(java.lang.String display)

Sets the String that will be displayed if a column value in an Entity has a null value. If not specified, it defaults to an empty String ("").

Parameters:

display - the null display String.

getScope

protected Scope getScope()

Returns the Scope that will limit the list of Entity objects displayed, and the order in which they are displayed.

The default implementation returns a scope using Scope.LIKE comparisons created from the parameters on the HttpServletRequest, if the SEARCH_PARAMETER exists on the HttpServletRequest with a value of SEARCH_PARAMETER_VALUE. Otherwise, an empty scope is returned. In addition, if the SORT_PARAMETER exists on the HttpServletRequest or getSortAttributeName() does not return null from the HttpSession, the Scope will also specify the ordering of the list.

Sub-classes may over-ride this method to return a scope other than the default. Note, however, that this method may be called multiple times, and must always return consistent results.

Returns:

the Scope.

See Also:

retrieveSet()

getSearchAttributeName

protected java.lang.String getSearchAttributeName()

Returns the name of the HttpSession attribute that contains the current search scope.

Returns:

the session attribute name.

getSortAttributeName

protected java.lang.String getSortAttributeName()

Returns the name of the HttpSession attribute that contains the current sort column.

Returns:

the session attribute name.

build

protected void build()
              throws java.sql.SQLException

Retrieves the required Entity objects specified by the scope, and adds them to the Table which is the parent of the row(s) returned by getRow(int).

Each cell in the row that is to be cleared and populated with an Anchor must have an ID attribute that matches the case-insensitive column name in the Entity.

Throws:

java.sql.SQLException - if an error occurs retrieving the Entity objects.

onCell

protected void onCell(int rowNumber,
                      Table.Cell cell,
                      Entity entity)

Called immediately after the cell has been processed, even if no Anchor was added to the cell. The default implementation does nothing.

Parameters:

rowNumber - the position in the list of the row which contains this cell. Note that the first position in the list is rowNumber 1.

cell - the populated cell.

entity - the entity that populated the row.

onFirstRow

protected void onFirstRow(Table.Row row,
                          Entity entity)

Called immediately after the first row has been added to the list table, but before the onRow(int, org.pajes.html.Table.Row, org.pajes.db.entity.Entity) method for the first row. The default implementation does nothing.

Parameters:

row - the populated row.

entity - the entity that populated the row.

onLastRow

protected void onLastRow(int rowNumber,
                         Table.Row row,
                         Entity entity)

Called after the last row has been added to the list table, and after the onRow(int, org.pajes.html.Table.Row, org.pajes.db.entity.Entity) method for the last row. The default implementation does nothing.

Parameters:

rowNumber - the position in the list of the specified row. Note that the first position in the list is rowNumber 1.

row - the populated row.

entity - the entity that populated the row.

onRow

protected void onRow(int rowNumber,
                     Table.Row row,
                     Entity entity)

Called immediately after the row has been added to the list table. The default implementation does nothing.

Parameters:

rowNumber - the position in the list of the specified row. Note that the first position in the list is rowNumber 1.

row - the populated row.

entity - the entity that populated the row.

See Also:

onFirstRow(org.pajes.html.Table.Row, org.pajes.db.entity.Entity), onLastRow(int, org.pajes.html.Table.Row, org.pajes.db.entity.Entity)

retrieveSet

protected Entity[] retrieveSet()
                        throws java.sql.SQLException

Returns the set of Entity objects to be displayed in the list.

The default implementation returns all entities that meet the scope.

Returns:

the array of Entity objects to be displayed in the list.

Throws:

java.sql.SQLException - if an error occurs retrieving the Entity objects.

See Also:

getScope()