Author: ekoneil
Date: Tue May 3 16:11:52 2005
New Revision: 168017
URL: http://svn.apache.org/viewcvs?rev=168017&view=rev
Log:
Javadoc for the data grid public APIs.
BB: self
DRT: NetUI pass
Modified:
incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/api/rendering/CellDecorator.java
incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/api/rendering/CellModel.java
incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/api/sort/Sort.java
incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/api/sort/SortDirection.java
incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/api/sort/SortModel.java
Modified:
incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/api/rendering/CellDecorator.java
URL:
http://svn.apache.org/viewcvs/incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/api/rendering/CellDecorator.java?rev=168017&r1=168016&r2=168017&view=diff
==============================================================================
---
incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/api/rendering/CellDecorator.java
(original)
+++
incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/api/rendering/CellDecorator.java
Tue May 3 16:11:52 2005
@@ -23,28 +23,71 @@
import
org.apache.beehive.netui.databinding.datagrid.api.exceptions.CellDecoratorException;
/**
- *
+ * <p>
+ * Abstract basee class used to render the contents of a data grid cell.
CellDecorators are used so that
+ * code used to render the contents of a data grid cell can be chained
together in order to compose
+ * different rendering patterns. For example, an HTML anchor and image
decorator could be composed together
+ * to create an image anchor renderer. In addition, cell decoration can be
used to display UI exposing
+ * custom data grid features such as sort or filter UI on data grid header
cells.
+ * </p>
+ * <p>
+ * CellDecorators are intended to be <b>stateless</b>. State required for
rendering should be passed to
+ * a CellDecorator using an instance of a [EMAIL PROTECTED] CellModel} class.
+ * </p>
*/
public abstract class CellDecorator {
+ /**
+ * This decorator can be optionally used by implementations to
+ * render additional UI for the cell.
+ */
private CellDecorator _cellDecorator = null;
+ /**
+ * Default constructor.
+ */
public CellDecorator() {
}
+ /**
+ * Constructor that takes a nested CellDecorator.
+ *
+ * @param cellDecorator the nested decorator which can optionally be used
by implementations
+ * to render additional UI for the cell.
+ */
public CellDecorator(CellDecorator cellDecorator) {
this();
_cellDecorator = cellDecorator;
}
+ /**
+ * Get the nested decorator.
+ *
+ * @return the cell decorator if one has been provided. <code>null</code>
otherwise.
+ */
public CellDecorator getNestedDecorator() {
return _cellDecorator;
}
+ /**
+ * Set the nested cell decorator.
+ *
+ * @param cellDecorator the cell decorator.
+ */
public void setNestedDecorator(CellDecorator cellDecorator) {
_cellDecorator = cellDecorator;
}
+ /**
+ * This method is implemented by subclasses to provide decoration
behavior. The use of a nested CellDecorator
+ * is left to specific implementations; it is possible that some
implementations will ignore such
+ * nested instances.
+ *
+ * @param jspContext the [EMAIL PROTECTED] JspContext} for the current page
+ * @param appender the [EMAIL PROTECTED] AbstractRenderAppender} to which
markup should be rendered
+ * @param cellModel the [EMAIL PROTECTED] CellModel} JavaBean that contains
+ * @throws CellDecoratorException an exception thrown when an error occurs
running the decorator.
+ */
public abstract void decorate(JspContext jspContext,
AbstractRenderAppender appender, CellModel cellModel)
throws CellDecoratorException;
}
Modified:
incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/api/rendering/CellModel.java
URL:
http://svn.apache.org/viewcvs/incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/api/rendering/CellModel.java?rev=168017&r1=168016&r2=168017&view=diff
==============================================================================
---
incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/api/rendering/CellModel.java
(original)
+++
incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/api/rendering/CellModel.java
Tue May 3 16:11:52 2005
@@ -38,14 +38,34 @@
private DataGridTagModel _dataGridTagModel;
private ArrayList/*<Formatter>*/ _formatters;
+ /**
+ * Get the [EMAIL PROTECTED] DataGridTagModel} which is associated with
the data grid tag that contains this
+ * cell.
+ *
+ * @return the [EMAIL PROTECTED] DataGridTagModel} for this cell. Inside
a valid data grid, this method should
+ * not return <code>null</code>.
+ */
public DataGridTagModel getDataGridTagModel() {
return _dataGridTagModel;
}
+ /**
+ * Set the [EMAIL PROTECTED] DataGridTagModel} for this cell.
+ *
+ * @param dataGridTagModel the new [EMAIL PROTECTED] DataGridTagModel}
value.
+ */
public void setDataGridTagModel(DataGridTagModel dataGridTagModel) {
_dataGridTagModel = dataGridTagModel;
}
+ /**
+ * Add a [EMAIL PROTECTED] Formatter} which can be used to format an
Object for rendering. Many
+ * [EMAIL PROTECTED] Formatter} instances can be registered and will be
executed in the order in
+ * which they were added. This method is provided as a service to
CellModel subclasses;
+ * the use of formatters can vary based on the implementation of a [EMAIL
PROTECTED] CellDecorator}.
+ *
+ * @param formatter the [EMAIL PROTECTED] Formatter} to add
+ */
public void addFormatter(Formatter formatter) {
if(_formatters == null)
_formatters = new ArrayList/*<Formatter>*/();
@@ -53,6 +73,15 @@
_formatters.add(formatter);
}
+ /**
+ * Format an [EMAIL PROTECTED] Object} value. This method can be called
by subclasses or by [EMAIL PROTECTED] CellDecorator} instances
+ * which need to format data before rendering.
+ *
+ * @param value the [EMAIL PROTECTED] Object} to format
+ * @return If the <code>value</code> is null, return <code>null</code>.
If there are no registered
+ * [EMAIL PROTECTED] Formatter} instances, return [EMAIL PROTECTED]
Object#toString()} for the <code>value</code> parameter.
+ * Otherwisee, return the formatted value.
+ */
public String formatText(Object value) {
if(value == null)
return null;
@@ -72,7 +101,7 @@
formatted = formatter.format(formatted);
}
catch(JspException e) {
- /* todo: error reporting */
+ /* todo: v1 -- error reporting */
LOGGER.error(Bundle.getErrorString("CellModel_FormatterThrewException", new
Object[]{formatter.getClass().getName(), e}), e);
}
}
Modified:
incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/api/sort/Sort.java
URL:
http://svn.apache.org/viewcvs/incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/api/sort/Sort.java?rev=168017&r1=168016&r2=168017&view=diff
==============================================================================
---
incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/api/sort/Sort.java
(original)
+++
incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/api/sort/Sort.java
Tue May 3 16:11:52 2005
@@ -18,17 +18,39 @@
package org.apache.beehive.netui.databinding.datagrid.api.sort;
/**
- *
- */
+ * <p>
+ * The Sort class is a JavaBean that abstractly represents the data needed to
calculate a sort
+ * on some data set. A sort consists of some [EMAIL PROTECTED] String}
expression and a [EMAIL PROTECTED] SortDirection}.
+ * The mechanism for performing the sort is not provided here.
+ * </p>
+ * <p>
+ * A Sort object can be used by some sorting infrastructure to either
parameterise a SQL or XQuery
+ * query or to simply sort in-memory Java objects. For example, when
converting a Sort into
+ * a SQL fragment, a Sort with sortExpression "foo" and sortDirection [EMAIL
PROTECTED] SortDirection.DESCENDING} could
+ * be converted into:
+ * <pre>
+ * ORDER BY FOO DESC
+ * </pre>
+ * </p>
+*/
public class Sort
implements java.io.Serializable {
private String _sortExpression;
private SortDirection _sortDirection;
+ /**
+ * Empty constructor.
+ */
public Sort() {
}
+ /**
+ * Constructs a Sort with the given <code>sortExpression</code> and
<code>sortDirection</code>.
+ *
+ * @param sortExpression the Sort's sort expression
+ * @param sortDirection the Sort's sort direction
+ */
public Sort(String sortExpression, SortDirection sortDirection) {
this();
_sortExpression = sortExpression;
Modified:
incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/api/sort/SortDirection.java
URL:
http://svn.apache.org/viewcvs/incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/api/sort/SortDirection.java?rev=168017&r1=168016&r2=168017&view=diff
==============================================================================
---
incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/api/sort/SortDirection.java
(original)
+++
incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/api/sort/SortDirection.java
Tue May 3 16:11:52 2005
@@ -18,6 +18,14 @@
package org.apache.beehive.netui.databinding.datagrid.api.sort;
/**
+ * <p>
+ * The SortDirection class is an abstract representation of the direction of a
sort. This class
+ * is able to represent a sort that is either [EMAIL PROTECTED]
SortDirection.ASCENDING}, [EMAIL PROTECTED] SortDirection.DESCENDING},
+ * or [EMAIL PROTECTED] SortDirection.NONE}.
+ * </p>
+ * <p>
+ * The SortDirection class should be used to specify the direction of a sort
on a [EMAIL PROTECTED] Sort} instance.
+ * </p>
*/
public class SortDirection
implements java.io.Serializable {
Modified:
incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/api/sort/SortModel.java
URL:
http://svn.apache.org/viewcvs/incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/api/sort/SortModel.java?rev=168017&r1=168016&r2=168017&view=diff
==============================================================================
---
incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/api/sort/SortModel.java
(original)
+++
incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/api/sort/SortModel.java
Tue May 3 16:11:52 2005
@@ -20,24 +20,57 @@
import java.util.List;
/**
- *
+ * <p>
+ * The SortModel class groups a set of [EMAIL PROTECTED] Sort} objects. This
class also provides a set of methods
+ * for interacting with a group of [EMAIL PROTECTED] Sort} objects.
+ * </p>
+ * <p>
+ * The list of [EMAIL PROTECTED] Sort} objects in a SortModel are ordered.
The first sort in group is known as the
+ * "primary" sort and subsequent Sorts are "secondary". The interpretation of
using Sorts into
+ * to order a data set is left to implementations of sort algoritms. For
example, one possible
+ * sort implementation could order the sorts such that the secondary sort
occurs inside the
+ * data ordered by the primary sort and so on.
+ * </p>
+ * <p>
+ * In addition to accessing the Sort objects, the SortModel provides a the
ability to plug a simple state
+ * machine that controls how to change a sort direction when cycling through
the set of sort directions.
+ * For example, when using a data grid to sort columns of data, a column may
start off unsorted,
+ * change to [EMAIL PROTECTED] SortDirection.ASCENDING}, to [EMAIL PROTECTED]
SortDirection.DESCENDING}, and finally back to
+ * [EMAIL PROTECTED] SortDirection.NONE}. The [EMAIL PROTECTED] SortStrategy}
allows this strategy to be changed so that the
+ * sorts can change from [EMAIL PROTECTED] SortDirection.NONE} to [EMAIL
PROTECTED] SortDirection.DESCENDING}, to
+ * [EMAIL PROTECTED] SortDirection.ASCENDING}, and finally back to [EMAIL
PROTECTED] SortDirection.NONE}.
+ * </p>
*/
public class SortModel
implements java.io.Serializable {
/* todo: consider exposing a Map getSortMap() that would be JSP 2.0 EL
bindable */
+ /* todo: expose a convenience method to change the direction of a sort */
private SortStrategy _sortStrategy = null;
private List/*<Sort>*/ _sorts = null;
+ /**
+ * Construct the SortModel with a [EMAIL PROTECTED] List} of sorts.
+ * @param sorts the sorts
+ */
public SortModel(List/*<Sort>*/ sorts) {
_sorts = sorts;
}
+ /**
+ * Get the [EMAIL PROTECTED] SortStrategy} used to cycle these [EMAIL
PROTECTED] Sort} objects through various
+ * [EMAIL PROTECTED] SortDirection}s.
+ * @return the [EMAIL PROTECTED] SortStrategy}
+ */
public SortStrategy getSortStrategy() {
return _sortStrategy;
}
+ /**
+ * Set the [EMAIL PROTECTED] SortStrategy}.
+ * @param sortStrategy the new [EMAIL PROTECTED] SortStrategy}
+ */
public void setSortStrategy(SortStrategy sortStrategy) {
_sortStrategy = sortStrategy;
}
@@ -49,6 +82,16 @@
return _sorts;
}
+ /**
+ * Check to see if a sort expression is the first [EMAIL PROTECTED] Sort}
in the [EMAIL PROTECTED] SortModel}. If the
+ * first [EMAIL PROTECTED] Sort} in the SortModel has a [EMAIL PROTECTED]
Sort#getSortExpression()} that matches the
+ * <code>sortExpression</code> parameter, the method returns
<code>true</code>. Otherwise, it
+ * returns <code>false</code>.
+ *
+ * @param sortExpression the sort expression to use when checking the
SortModel's first [EMAIL PROTECTED] Sort}
+ * @return <code>true</code> if the first [EMAIL PROTECTED] Sort} has a
sortExpression that matches the
+ * sortExpression parameter. <code>false</code> otherwise.
+ */
public boolean isPrimarySort(String sortExpression) {
if(sortExpression == null)
return false;
@@ -63,6 +106,14 @@
return false;
}
+ /**
+ * Check to see if the SortModel contains a [EMAIL PROTECTED] Sort} whose
sort expression matches the given
+ * <code>sortExpression</code>.
+ *
+ * @param sortExpression the sortExpression used to locate a [EMAIL
PROTECTED] Sort}
+ * @return <code>true</code> if a [EMAIL PROTECTED] Sort} is found whose
[EMAIL PROTECTED] Sort#getSortExpression()} matches
+ * the given <code>sortExpression</code>. <code>false</code> otherwise.
+ */
public boolean isSorted(String sortExpression) {
if(sortExpression == null)
return false;
@@ -73,11 +124,26 @@
else return true;
}
+ /**
+ * Get the [EMAIL PROTECTED] SortDirection} for a [EMAIL PROTECTED] Sort}
given a sort expression.
+ *
+ * @param sortExpression the sort expression used to locate a [EMAIL
PROTECTED] Sort} object.
+ * @return a [EMAIL PROTECTED] Sort}'s [EMAIL PROTECTED] SortDirection} if
one is found whose <code>sortExpression</code>
+ * property matches the given <code>sortExpression</code>.
<code>null</code> otherwise.
+ */
public SortDirection getSortDirection(String sortExpression) {
Sort term = findSort(sortExpression);
return term == null ? SortDirection.NONE : term.getDirection();
}
+ /**
+ * Lookup a [EMAIL PROTECTED] Sort} object whose [EMAIL PROTECTED]
Sort#getSortExpression()} matches
+ * the given <code>sortExpression</code>.
+ *
+ * @param sortExpression the sortExpression used to locate a [EMAIL
PROTECTED] Sort}
+ * @return a [EMAIL PROTECTED] Sort} if one is found whose
<code>sortExpression</code> property matches
+ * the given <code>sortExpression</code>. <code>null</code> otherwise.
+ */
public Sort lookupSort(String sortExpression) {
return findSort(sortExpression);
}
