org.apache.jetspeed.portlets.layout
Class ColumnLayout

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

All Implemented Interfaces:

java.io.Serializable

public class ColumnLayout
extends java.lang.Object
implements java.io.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 individual 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

Constructor Summary

ColumnLayout(int numberOfColumns, java.lang.String layoutType, java.util.Collection<ContentFragment> fragments, java.lang.String[] columnWidths)

ColumnLayout(int numberOfColumns, java.lang.String layoutType, java.util.Collection<ContentFragment> fragments, java.lang.String[] columnWidths, ContentFragment maximized)
Same as ColumnLayout(int numberOfColumns, String layoutType) but also supplies a Collection of fragments to initially populate the layout with.

ColumnLayout(int numberOfColumns, java.lang.String layoutType, java.lang.String[] columnWidths)

Method Summary

void	addFragment(ContentFragment 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 dispatched.
void	buildDetachedPortletList(java.util.Collection<ContentFragment> fragments)
protected void	doAdd(int columnNumber, int rowNumber, ContentFragment fragment) Adds a fragment at the indicated columnNumber and rowNumber.
protected void	doMove(ContentFragment fragment, LayoutCoordinate oldCoordinate, LayoutCoordinate newCoordinate) Performs the actual movement of a fragment.
protected int	getColumn(ContentFragment fragment) Gets the row number of this fragment to looking the layoutType property column.
java.util.Collection<ContentFragment>	getColumn(int columnNumber)
java.lang.String	getColumnFloat(int columnNumber) returns the float to be used with the specified column.
protected java.util.SortedMap<java.lang.Integer,ContentFragment>	getColumnMap(int columnNumber) Retrieves this specified columnNumber as a SortedMap.
java.util.Collection<java.util.Collection<ContentFragment>>	getColumns()
java.lang.String	getColumnWidth(int columnNumber) returns the width to be used with the specified column.
LayoutCoordinate	getCoordinate(ContentFragment fragment)
java.util.List<ContentFragment>	getDetachedPortlets()
java.util.Collection<ContentFragment>	getFirstColumn()
ContentFragment	getFragmentAt(int columnNumber, int rowNumber) Retrieves the fragment at the specified loaction.
ContentFragment	getFragmentAt(LayoutCoordinate coodinate) Retrieves the fragment at the specified loaction.
java.util.Collection<ContentFragment>	getFragments() Returns an immutable Collection of all the Fragments contained within this ColumnLayout in no sepcific order.
java.util.Collection<ContentFragment>	getLastColumn()
int	getLastRowNumber(int columnNumber) Returns the index of the last row in the specified column.
int	getNumberOfColumns()
protected int	getRow(int currentColumn, ContentFragment fragment) Gets the row number of this fragment to looking the layoutType property row.
void	moveDown(ContentFragment fragment)
void	moveLeft(ContentFragment fragment) Moves a fragment one column to the left.
void	moveRight(ContentFragment fragment) Moves a fragment one column to the right.
void	moveUp(ContentFragment 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

Constructor Detail

ColumnLayout

public ColumnLayout(int numberOfColumns,
                    java.lang.String layoutType,
                    java.lang.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 segregation 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,
                    java.lang.String layoutType,
                    java.util.Collection<ContentFragment> fragments,
                    java.lang.String[] columnWidths,
                    ContentFragment maximized)
             throws LayoutEventException

Same as ColumnLayout(int numberOfColumns, String layoutType) but also supplies a Collection of fragments 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 segregation 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)

ColumnLayout

public ColumnLayout(int numberOfColumns,
                    java.lang.String layoutType,
                    java.util.Collection<ContentFragment> fragments,
                    java.lang.String[] columnWidths)
             throws LayoutEventException

Throws:

LayoutEventException

Method Detail

addFragment

public void addFragment(ContentFragment 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 dispatched.

Parameters:

eventListener -

See Also:

LayoutEventListener, LayoutEventListener

getColumn

public java.util.Collection<ContentFragment> 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 java.lang.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 java.lang.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 java.util.Collection<java.util.Collection<ContentFragment>> 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 java.util.Collection<ContentFragment> getFragments()

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

Returns:

Immutable Collection of Fragments.

getFragmentAt

public ContentFragment 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 ContentFragment 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 java.util.Collection<ContentFragment> getLastColumn()

Returns:

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

getFirstColumn

public java.util.Collection<ContentFragment> getFirstColumn()

Returns:

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

moveRight

public void moveRight(ContentFragment 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(ContentFragment 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(ContentFragment 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(ContentFragment 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(ContentFragment 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(ContentFragment 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,
                     ContentFragment 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 java.util.SortedMap<java.lang.Integer,ContentFragment> getColumnMap(int columnNumber)
                                                                             throws InvalidLayoutLocationException

Retrieves this specified columnNumber as a SortedMap.

Parameters:

columnNumber -

Returns:

SortedMap

Throws:

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

getRow

protected final int getRow(int currentColumn,
                           ContentFragment 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(ContentFragment 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.

getDetachedPortlets

public java.util.List<ContentFragment> getDetachedPortlets()

buildDetachedPortletList

public void buildDetachedPortletList(java.util.Collection<ContentFragment> fragments)