You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@beehive.apache.org by ek...@apache.org on 2005/05/04 01:11:54 UTC
svn commit: r168017 - in
/incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/api:
rendering/CellDecorator.java rendering/CellModel.java sort/Sort.java
sort/SortDirection.java sort/SortModel.java
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 {@link 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 {@link JspContext} for the current page
+ * @param appender the {@link AbstractRenderAppender} to which markup should be rendered
+ * @param cellModel the {@link 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 {@link DataGridTagModel} which is associated with the data grid tag that contains this
+ * cell.
+ *
+ * @return the {@link DataGridTagModel} for this cell. Inside a valid data grid, this method should
+ * not return <code>null</code>.
+ */
public DataGridTagModel getDataGridTagModel() {
return _dataGridTagModel;
}
+ /**
+ * Set the {@link DataGridTagModel} for this cell.
+ *
+ * @param dataGridTagModel the new {@link DataGridTagModel} value.
+ */
public void setDataGridTagModel(DataGridTagModel dataGridTagModel) {
_dataGridTagModel = dataGridTagModel;
}
+ /**
+ * Add a {@link Formatter} which can be used to format an Object for rendering. Many
+ * {@link 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 {@link CellDecorator}.
+ *
+ * @param formatter the {@link Formatter} to add
+ */
public void addFormatter(Formatter formatter) {
if(_formatters == null)
_formatters = new ArrayList/*<Formatter>*/();
@@ -53,6 +73,15 @@
_formatters.add(formatter);
}
+ /**
+ * Format an {@link Object} value. This method can be called by subclasses or by {@link CellDecorator} instances
+ * which need to format data before rendering.
+ *
+ * @param value the {@link Object} to format
+ * @return If the <code>value</code> is null, return <code>null</code>. If there are no registered
+ * {@link Formatter} instances, return {@link 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 {@link String} expression and a {@link 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 {@link 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 {@link SortDirection.ASCENDING}, {@link SortDirection.DESCENDING},
+ * or {@link SortDirection.NONE}.
+ * </p>
+ * <p>
+ * The SortDirection class should be used to specify the direction of a sort on a {@link 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 {@link Sort} objects. This class also provides a set of methods
+ * for interacting with a group of {@link Sort} objects.
+ * </p>
+ * <p>
+ * The list of {@link 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 {@link SortDirection.ASCENDING}, to {@link SortDirection.DESCENDING}, and finally back to
+ * {@link SortDirection.NONE}. The {@link SortStrategy} allows this strategy to be changed so that the
+ * sorts can change from {@link SortDirection.NONE} to {@link SortDirection.DESCENDING}, to
+ * {@link SortDirection.ASCENDING}, and finally back to {@link 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 {@link List} of sorts.
+ * @param sorts the sorts
+ */
public SortModel(List/*<Sort>*/ sorts) {
_sorts = sorts;
}
+ /**
+ * Get the {@link SortStrategy} used to cycle these {@link Sort} objects through various
+ * {@link SortDirection}s.
+ * @return the {@link SortStrategy}
+ */
public SortStrategy getSortStrategy() {
return _sortStrategy;
}
+ /**
+ * Set the {@link SortStrategy}.
+ * @param sortStrategy the new {@link SortStrategy}
+ */
public void setSortStrategy(SortStrategy sortStrategy) {
_sortStrategy = sortStrategy;
}
@@ -49,6 +82,16 @@
return _sorts;
}
+ /**
+ * Check to see if a sort expression is the first {@link Sort} in the {@link SortModel}. If the
+ * first {@link Sort} in the SortModel has a {@link 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 {@link Sort}
+ * @return <code>true</code> if the first {@link 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 {@link Sort} whose sort expression matches the given
+ * <code>sortExpression</code>.
+ *
+ * @param sortExpression the sortExpression used to locate a {@link Sort}
+ * @return <code>true</code> if a {@link Sort} is found whose {@link 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 {@link SortDirection} for a {@link Sort} given a sort expression.
+ *
+ * @param sortExpression the sort expression used to locate a {@link Sort} object.
+ * @return a {@link Sort}'s {@link 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 {@link Sort} object whose {@link Sort#getSortExpression()} matches
+ * the given <code>sortExpression</code>.
+ *
+ * @param sortExpression the sortExpression used to locate a {@link Sort}
+ * @return a {@link 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);
}