org.apache.jetspeed.portlets.layout
Class ColumnLayout

java.lang.Object
  org.apache.jetspeed.portlets.layout.ColumnLayout

All Implemented Interfaces:

Serializable

public class ColumnLayout
extends Object
implements Serializable

Basics

ColumnLayout is the model used to support any 1 to n column-based layout. ColumnLayout is constrained by a number columns that will not be exceeded, even if a fragment specifies a column outside of this constraint. Any fragment exceeded the specified column constraint will be deposited into the right-most column.

Characteristics:

• Columns and rows always start at 0.
• Unless otherwise noted, assume all Collections returned are immutable.
• Unless otherwise noted, assume that no public method will ever return null.

Layout Events

When any move*() method is invoked and a portlet is actually moved (see indvidual methods for what causes these circumstances), an initial LayoutEvent is dispatched. This may cause a cascade of LayoutEvents to be fired in turn if the movement of the target fragment cause other fragments to be repositioned. In this case a LayoutEvent is dispatched for each portlet moved, which in turn may our may not cause another LayoutEvent to be fired.

Author:

Scott T. Weaver

See Also:

LayoutEvent, LayoutEventListener, LayoutCoordinate, Fragment, Serialized Form

Field Summary

private SortedMap	columns SortedMap of Columns (which are also sorted maps
private String[]	columnWidths Width settings for eacah column
private Map	coordinates maps Fragments (key) to it's current LayoutCoordinate (value) in this layout
private List	eventListeners All of the LayoutEventListeners registered to this layout
private int[]	nextRowNumber Efficent way to always be aware of the next available row in a column
private int	numberOfColumns Constrains the columns for this layout
private static DecimalFormat	PERCENTAGE_WIDTH_FORMAT Percentage widths format
private static double	PERCENTAGE_WIDTH_GUTTER Percentage widths gutter width

Constructor Summary

ColumnLayout(int numberOfColumns, String layoutType, Collection fragments, String[] columnWidths)
Same as ColumnLayout(int numberOfColumns, String layoutType) but also supplies a Collection of fragmetns to initially populate the layout with.

ColumnLayout(int numberOfColumns, String layoutType, String[] columnWidths)

Method Summary

void	addFragment(org.apache.jetspeed.om.page.Fragment fragment) Adds a fragment to the layout using fragment properties of row and column as hints on where to put this fragment.
void	addLayoutEventListener(LayoutEventListener eventListener) Adds a LayoutEventListener to this layout that will be fired any time a LayoutEvent is disaptched.
protected void	doAdd(int columnNumber, int rowNumber, org.apache.jetspeed.om.page.Fragment fragment) Adds a fragment at the indicated columnNumber and rowNumber.
protected void	doMove(org.apache.jetspeed.om.page.Fragment fragment, LayoutCoordinate oldCoordinate, LayoutCoordinate newCoordinate) Performs the actual movement of a fragment.
protected int	getColumn(org.apache.jetspeed.om.page.Fragment fragment) Gets the row number of this fragment to looking the layoutType property column.
Collection	getColumn(int columnNumber)
String	getColumnFloat(int columnNumber) returns the float to be used with the specified column.
protected SortedMap	getColumnMap(int columnNumber) Retrieves this specified columnNumber as a SortedMap.
Collection	getColumns()
String	getColumnWidth(int columnNumber) returns the width to be used with the specified column.
LayoutCoordinate	getCoordinate(org.apache.jetspeed.om.page.Fragment fragment)
Collection	getFirstColumn()
org.apache.jetspeed.om.page.Fragment	getFragmentAt(int columnNumber, int rowNumber) Retrieves the fragment at the specified loaction.
org.apache.jetspeed.om.page.Fragment	getFragmentAt(LayoutCoordinate coodinate) Retrieves the fragment at the specified loaction.
Collection	getFragments() Returns an immutable Collection of all the Fragments contained within this ColumnLayout in no sepcific order.
Collection	getLastColumn()
int	getLastRowNumber(int columnNumber) Returns the index of the last row in the specified column.
int	getNumberOfColumns()
protected int	getRow(int currentColumn, org.apache.jetspeed.om.page.Fragment fragment) Gets the row number of this fragment to looking the layoutType property row.
void	moveDown(org.apache.jetspeed.om.page.Fragment fragment)
void	moveLeft(org.apache.jetspeed.om.page.Fragment fragment) Moves a fragment one column to the left.
void	moveRight(org.apache.jetspeed.om.page.Fragment fragment) Moves a fragment one column to the right.
void	moveUp(org.apache.jetspeed.om.page.Fragment fragment) Moves a fragment one row to the up.
protected void	processEvent(LayoutEvent event) Dispatches a LayoutEvent to all LayoutEventListeners registered to this layout.

Methods inherited from class java.lang.Object

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

Field Detail

PERCENTAGE_WIDTH_GUTTER

private static final double PERCENTAGE_WIDTH_GUTTER

Percentage widths gutter width

See Also:

Constant Field Values

PERCENTAGE_WIDTH_FORMAT

private static final DecimalFormat PERCENTAGE_WIDTH_FORMAT

Percentage widths format

numberOfColumns

private final int numberOfColumns

Constrains the columns for this layout

columns

private final SortedMap columns

SortedMap of Columns (which are also sorted maps

columnWidths

private final String[] columnWidths

Width settings for eacah column

nextRowNumber

private final int[] nextRowNumber

Efficent way to always be aware of the next available row in a column

coordinates

private final Map coordinates

maps Fragments (key) to it's current LayoutCoordinate (value) in this layout

eventListeners

private final List eventListeners

All of the LayoutEventListeners registered to this layout

Constructor Detail

ColumnLayout

public ColumnLayout(int numberOfColumns,
                    String layoutType,
                    String[] columnWidths)

Parameters:

numberOfColumns - the maximum number of columns this layout will have.

layoutType - this value corresponds to the property settings of the fragments within your psml. Layout type allows segration of property settings based on the type of layout in use. This effectively allows for the interchange of multiple layout formats without one format effecting the settings of another.

columnWidths - widths for each column that accumulate to 100% if percentages are used.

See Also:

Fragment.getType()

ColumnLayout

public ColumnLayout(int numberOfColumns,
                    String layoutType,
                    Collection fragments,
                    String[] columnWidths)
             throws LayoutEventException

Same as ColumnLayout(int numberOfColumns, String layoutType) but also supplies a Collection of fragmetns to initially populate the layout with. Adding these fragments WILL NOT cause a LayoutEvent to be dispatched.

Parameters:

numberOfColumns - the maximum number of columns this layout will have.

layoutType - this value corresponds to the property settings of the fragments within your psml. Layout type allows segration of property settings based on the type of layout in use. This effectively allows for the interchange of multiple layout formats without one format effecting the settings of another.

fragments - Initial set of fragments to add to this layout.

columnWidths - widths for each column that accumulate to 100% if percentages are used.

Throws:

LayoutEventException

See Also:

ColumnLayout(int numberOfColumns, String layoutType)

Method Detail

addFragment

public void addFragment(org.apache.jetspeed.om.page.Fragment fragment)
                 throws LayoutEventException

Adds a fragment to the layout using fragment properties of row and column as hints on where to put this fragment. The following rules apply to malformed fragment definitions:

• Fragments without a row defined are placed at the bottom of their respective column
• Fragments without a column are placed in the right-most column.
• Fragments with overlapping row numbers. The last fragment has priority pushing the fragment in that row down one row.

Parameters:

fragment - Fragment to add to this layout.

Throws:

LayoutEventException

See Also:

Fragment

addLayoutEventListener

public void addLayoutEventListener(LayoutEventListener eventListener)

Adds a LayoutEventListener to this layout that will be fired any time a LayoutEvent is disaptched.

Parameters:

eventListener -

See Also:

LayoutEventListener, LayoutEventListener

getColumn

public Collection getColumn(int columnNumber)
                     throws InvalidLayoutLocationException

Parameters:

columnNumber - Number of column to retreive

Returns:

requested column (as a immutable Collection). Never returns null.

Throws:

InvalidLayoutLocationException - if the column is outisde of the constraints of this layout

getColumnWidth

public String getColumnWidth(int columnNumber)

returns the width to be used with the specified column. If there is no specific column setting sfor the specified column 0 is returned.

Parameters:

columnNumber - whose width has been requested.

Returns:

the width to be used with the specified column. Or 0 if no value has been specified.

getColumnFloat

public String getColumnFloat(int columnNumber)

returns the float to be used with the specified column.

Parameters:

columnNumber - whose width has been requested.

Returns:

"right" for the last column, "left" if more than one column, or "none" otherwise.

getColumns

public Collection getColumns()

Returns:

java.util.Collection all of columns (also Collection objects) in order within this layout. All Collections are immutable.

getLastRowNumber

public int getLastRowNumber(int columnNumber)

Returns the index of the last row in the specified column.

Parameters:

columnNumber - column form whom we ant to identify the last row.

Returns:

the index of the last row in the specified column.

getFragments

public Collection getFragments()

Returns an immutable Collection of all the Fragments contained within this ColumnLayout in no sepcific order.

Returns:

Immutable Collection of Fragments.

getFragmentAt

public org.apache.jetspeed.om.page.Fragment getFragmentAt(int columnNumber,
                                                          int rowNumber)
                                                   throws EmptyLayoutLocationException,
                                                          InvalidLayoutLocationException

Retrieves the fragment at the specified loaction.

Parameters:

columnNumber - Column coordinate (first column starts at 0)

rowNumber - Row coordinate (first row starts at 0)

Returns:

Fragment at the specified coordinate. Never returns null.

Throws:

EmptyLayoutLocationException - if there is no fragment currently located at the specified coordinate.

InvalidLayoutLocationException - if the coordinate lies outside the confines of this layout, i.e., the columnNumber exceeds the max columns setting for this layout.

getFragmentAt

public org.apache.jetspeed.om.page.Fragment getFragmentAt(LayoutCoordinate coodinate)
                                                   throws EmptyLayoutLocationException,
                                                          InvalidLayoutLocationException

Retrieves the fragment at the specified loaction.

Parameters:

coodinate - LayoutCoordinate object that will be used to located a fragment in this layout.

Returns:

Fragment at the specified coordinate. Never returns null.

Throws:

EmptyLayoutLocationException - if there is no fragment currently located at the specified coordinate.

InvalidLayoutLocationException - if the coordinate lies outside the confines of this layout, i.e., the columnNumber exceeds the max columns setting for this layout.

See Also:

LayoutCoordinate, LayoutCoordinate

getNumberOfColumns

public int getNumberOfColumns()

Returns:

The total number of columns in this layout.

getLastColumn

public Collection getLastColumn()

Returns:

The last column in this layout. The Collection is immutable.

getFirstColumn

public Collection getFirstColumn()

Returns:

The last column in this layout. The Collection is immutable.

moveRight

public void moveRight(org.apache.jetspeed.om.page.Fragment fragment)
               throws FragmentNotInLayoutException,
                      LayoutEventException

Moves a fragment one column to the right. A LayoutEvent is triggered by this action.

If the fragment currently resides in right-most column, no action is taking and no event LayoutEvent is fired.

Parameters:

fragment - fragment to move.

Throws:

FragmentNotInLayoutException - if the specified fragment is not currently in the layout.

LayoutEventException - If a triggered LayoutEvent fails.

moveLeft

public void moveLeft(org.apache.jetspeed.om.page.Fragment fragment)
              throws FragmentNotInLayoutException,
                     LayoutEventException

Moves a fragment one column to the left. A LayoutEvent is triggered by this action.

If the fragment currently resides in left-most column, no action is taking and no event LayoutEvent is fired.

Parameters:

fragment -

Throws:

FragmentNotInLayoutException - if the specified fragment is not currently in the layout.

LayoutEventException - If a triggered LayoutEvent fails.

moveUp

public void moveUp(org.apache.jetspeed.om.page.Fragment fragment)
            throws FragmentNotInLayoutException,
                   LayoutEventException

Moves a fragment one row to the up. A LayoutEvent is triggered by this action.

If the fragment currently resides in top-most row, no action is taking and no event LayoutEvent is fired.

Parameters:

fragment -

Throws:

FragmentNotInLayoutException - if the specified fragment is not currently in the layout.

LayoutEventException - If a triggered LayoutEvent fails.

moveDown

public void moveDown(org.apache.jetspeed.om.page.Fragment fragment)
              throws FragmentNotInLayoutException,
                     LayoutEventException

Parameters:

fragment -

Throws:

FragmentNotInLayoutException - if the specified fragment is not currently in the layout.

LayoutEventException - If a triggered LayoutEvent fails.

doMove

protected void doMove(org.apache.jetspeed.om.page.Fragment fragment,
                      LayoutCoordinate oldCoordinate,
                      LayoutCoordinate newCoordinate)
               throws InvalidLayoutLocationException,
                      LayoutEventException

Performs the actual movement of a fragment.

Parameters:

fragment -

oldCoordinate -

newCoordinate -

Throws:

InvalidLayoutLocationException

LayoutEventException

getCoordinate

public LayoutCoordinate getCoordinate(org.apache.jetspeed.om.page.Fragment fragment)
                               throws FragmentNotInLayoutException

Parameters:

fragment - fragment whose LayoutCoordinate we ant.

Returns:

LayoutCoordinate representing the current location of this Fragment within this layout.

Throws:

FragmentNotInLayoutException - if the Fragment is not present in this layout.

See Also:

LayoutCoordinate

doAdd

protected void doAdd(int columnNumber,
                     int rowNumber,
                     org.apache.jetspeed.om.page.Fragment fragment)
              throws InvalidLayoutLocationException,
                     LayoutEventException

Adds a fragment at the indicated columnNumber and rowNumber.

Parameters:

columnNumber -

rowNumber -

fragment -

Throws:

InvalidLayoutLocationException - if the coordinates are outside the bounds of this layout.

LayoutEventException - id a LayoutEvent fails

getColumnMap

protected final SortedMap getColumnMap(int columnNumber)
                                throws InvalidLayoutLocationException

Retrieves this specified columnNumber as a SortedMap.

Parameters:

columnNumber -

Returns:

Throws:

InvalidLayoutLocationException - if the columnNumber resides outside the bounds of this layout.

getRow

protected final int getRow(int currentColumn,
                           org.apache.jetspeed.om.page.Fragment fragment)

Gets the row number of this fragment to looking the layoutType property row. If this property is undefined, the bottom-most row number of currentColumn is returned.

Parameters:

currentColumn -

fragment -

Returns:

valid row for this fragment within this layout.

getColumn

protected final int getColumn(org.apache.jetspeed.om.page.Fragment fragment)

Gets the row number of this fragment to looking the layoutType property column. If the column is undefined or exceeds the constriants of this layout, the value returned is numberOfColumns - 1. If the value is less than 0, 0 is returned.

Parameters:

fragment -

Returns:

processEvent

protected final void processEvent(LayoutEvent event)
                           throws LayoutEventException

Dispatches a LayoutEvent to all LayoutEventListeners registered to this layout.

Parameters:

event -

Throws:

LayoutEventException - if an error occurs while processing a the LayoutEvent.