001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.jetspeed.layout;
018:
019: import org.apache.jetspeed.om.page.Fragment;
020: import org.apache.jetspeed.om.page.Page;
021:
022: /**
023: * Handles portlet placement for client such as AJAX client side
024: * on a per request basis. The context is associated with a request context,
025: * thus it is only valid for the span of a request.
026: *
027: * @author <a>David Gurney</a>
028: * @author <a href="mailto:taylor@apache.org">David Sean Taylor</a>
029: * @version $Id: $
030: */
031: public interface PortletPlacementContext {
032: /**
033: * Move a portlet fragment to a new absolute position as specified in the Coordinate parameter.
034: *
035: * @param fragment The fragment to be moved.
036: * @param coordinate The specification of the new absolute coordinate
037: * @return new coordinate location of the portlet
038: * @throws PortletPlacementException
039: */
040: public Coordinate moveAbsolute(Fragment fragment,
041: Coordinate coordinate) throws PortletPlacementException;
042:
043: /**
044: * Move a portlet fragment to a new absolute position as specified in the Coordinate parameter.
045: *
046: * @param fragment The fragment to be moved.
047: * @param coordinate The specification of the new absolute coordinate
048: * @param addFragment When true, the fragment is being added (i.e. it is not being moved within the column)
049: * @return new coordinate location of the portlet
050: * @throws PortletPlacementException
051: */
052: public Coordinate moveAbsolute(Fragment fragment,
053: Coordinate coordinate, boolean addFragment)
054: throws PortletPlacementException;
055:
056: /**
057: * Move a portlet relative to its current position UP one row.
058: *
059: * @param fragment The fragment to be moved.
060: * @return new coordinate location of the portlet
061: * @throws PortletPlacementException
062: */
063: public Coordinate moveUp(Fragment fragment)
064: throws PortletPlacementException;
065:
066: /**
067: * Move a portlet relative to its current position DOWN one row.
068: *
069: * @param fragment The fragment to be moved.
070: * @return new coordinate location of the portlet
071: * @throws PortletPlacementException
072: */
073: public Coordinate moveDown(Fragment fragment)
074: throws PortletPlacementException;
075:
076: /**
077: * Move a portlet relative to its current position LEFT one column.
078: *
079: * @param fragment The fragment to be moved.
080: * @return new coordinate location of the portlet
081: * @throws PortletPlacementException
082: */
083: public Coordinate moveLeft(Fragment fragment)
084: throws PortletPlacementException;
085:
086: /**
087: * Move a portlet relative to its current position RIGHT one column.
088: *
089: * @param fragment The fragment to be moved.
090: * @return new coordinate location of the portlet
091: * @throws PortletPlacementException
092: */
093: public Coordinate moveRight(Fragment fragment)
094: throws PortletPlacementException;
095:
096: /**
097: * Add a portlet to its managed page.
098: *
099: * @param fragment The Fragment to add
100: * @param coordinate The coordinate where to place the new portlet
101: * @return
102: * @throws PortletPlacementException
103: */
104: public Coordinate add(Fragment fragment, Coordinate coordinate)
105: throws PortletPlacementException;
106:
107: /**
108: * Remove the specified fragment.
109: * @param fragment
110: * @return
111: * @throws PortletPlacementException
112: */
113: public Coordinate remove(Fragment fragment)
114: throws PortletPlacementException;
115:
116: /**
117: * retrieve the number of columns for the managed layout.
118: *
119: * @return the number of columns in the manged layout
120: * @throws PortletPlacementException
121: */
122: public int getNumberColumns() throws PortletPlacementException;
123:
124: /**
125: * retrieve the number of rows for the managed layout at the given column.
126: *
127: * @param column the column to retrieve the number of rows for
128: * @return the number of rows for the given column
129: * @throws PortletPlacementException
130: */
131: public int getNumberRows(int column)
132: throws PortletPlacementException;
133:
134: /**
135: * Retrieve a portlet fragment for the given coordinate.
136: *
137: * @param coordinate the coordinate associated to a fragment.
138: * @return the fragment associated to the given coordinate
139: * @throws PortletPlacementException
140: */
141: public Fragment getFragmentAtNewCoordinate(Coordinate coordinate)
142: throws PortletPlacementException;
143:
144: /**
145: * Retrieve the old portlet fragment for the given coordinate (prior to placement).
146: *
147: * @param coordinate the coordinate associated to a fragment.
148: * @return the fragment associated to the given coordinate
149: * @throws PortletPlacementException
150: */
151: public Fragment getFragmentAtOldCoordinate(Coordinate coordinate)
152: throws PortletPlacementException;
153:
154: /**
155: * Retrieve a fragment by fragment id.
156: *
157: * @param fragmentId a string key for a fragment managed on this layout.
158: * @return The fragment associated with the given fragment id.
159: * @throws PortletPlacementException
160: */
161: public Fragment getFragmentById(String fragmentId)
162: throws PortletPlacementException;
163:
164: /**
165: * Takes the internal portlet placement state and writes it back
166: * out to the root fragment for the managed page layout.
167: *
168: * @return the managed page layout with updated fragment state.
169: */
170: public Page syncPageFragments();
171:
172: }
|