View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    * 
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   * 
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.jetspeed.layout;
18  
19  import org.apache.jetspeed.om.page.Fragment;
20  import org.apache.jetspeed.om.page.Page;
21  
22  /***
23   * Handles portlet placement for client such as AJAX client side
24   * on a per request basis. The context is associated with a request context,
25   * thus it is only valid for the span of a request.  
26   *
27   * @author <a>David Gurney</a>
28   * @author <a href="mailto:taylor@apache.org">David Sean Taylor</a>
29   * @version $Id: $
30   */
31  public interface PortletPlacementContext 
32  {
33  	/***
34       * Move a portlet fragment to a new absolute position as specified in the Coordinate parameter.
35       * 
36  	 * @param fragment The fragment to be moved.
37  	 * @param coordinate The specification of the new absolute coordinate
38  	 * @return new coordinate location of the portlet
39  	 * @throws PortletPlacementException
40  	 */
41  	public Coordinate moveAbsolute(Fragment fragment, Coordinate coordinate ) throws PortletPlacementException;
42  
43  	/***
44       * Move a portlet fragment to a new absolute position as specified in the Coordinate parameter.
45       * 
46  	 * @param fragment The fragment to be moved.
47  	 * @param coordinate The specification of the new absolute coordinate
48  	 * @param addFragment When true, the fragment is being added (i.e. it is not being moved within the column)
49  	 * @return new coordinate location of the portlet
50  	 * @throws PortletPlacementException
51  	 */
52  	public Coordinate moveAbsolute(Fragment fragment, Coordinate coordinate, boolean addFragment) throws PortletPlacementException;
53  	
54  	/***
55       * Move a portlet relative to its current position UP one row.
56       * 
57       * @param fragment The fragment to be moved.
58       * @return new coordinate location of the portlet
59  	 * @throws PortletPlacementException
60  	 */
61  	public Coordinate moveUp(Fragment fragment) throws PortletPlacementException;
62  
63      /***
64       * Move a portlet relative to its current position DOWN one row.
65       * 
66       * @param fragment The fragment to be moved.
67       * @return new coordinate location of the portlet
68       * @throws PortletPlacementException
69       */    
70  	public Coordinate moveDown(Fragment fragment) throws PortletPlacementException;
71      
72      /***
73       * Move a portlet relative to its current position LEFT one column.
74       * 
75       * @param fragment The fragment to be moved.
76       * @return new coordinate location of the portlet
77       * @throws PortletPlacementException
78       */        
79  	public Coordinate moveLeft(Fragment fragment) throws PortletPlacementException;
80      
81      /***
82       * Move a portlet relative to its current position RIGHT one column.
83       * 
84       * @param fragment The fragment to be moved.
85       * @return new coordinate location of the portlet
86       * @throws PortletPlacementException
87       */            
88  	public Coordinate moveRight(Fragment fragment) throws PortletPlacementException;
89      
90  	/***
91       * Add a portlet to its managed page.
92       * 
93  	 * @param fragment The Fragment to add
94  	 * @param coordinate The coordinate where to place the new portlet
95  	 * @return
96  	 * @throws PortletPlacementException
97  	 */
98  	public Coordinate add(Fragment fragment, Coordinate coordinate) throws PortletPlacementException;
99      
100 	/***
101      * Remove the specified fragment.
102 	 * @param fragment
103 	 * @return
104 	 * @throws PortletPlacementException
105 	 */
106 	public Coordinate remove(Fragment fragment) throws PortletPlacementException;
107     
108     /***
109      * retrieve the number of columns for the managed layout.
110      * 
111      * @return the number of columns in the manged layout
112      * @throws PortletPlacementException
113      */
114 	public int getNumberColumns() throws PortletPlacementException;
115     
116     /***
117      * retrieve the number of rows for the managed layout at the given column.
118      * 
119      * @param column the column to retrieve the number of rows for
120      * @return the number of rows for the given column
121      * @throws PortletPlacementException
122      */    
123 	public int getNumberRows(int column) throws PortletPlacementException;
124     
125 	/***
126      * Retrieve a portlet fragment for the given coordinate.
127      *  
128 	 * @param coordinate the coordinate associated to a fragment.
129 	 * @return the fragment associated to the given coordinate
130 	 * @throws PortletPlacementException
131 	 */
132 	public Fragment getFragmentAtNewCoordinate(Coordinate coordinate) throws PortletPlacementException;
133     
134 	/***
135      * Retrieve the old portlet fragment for the given coordinate (prior to placement).
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 getFragmentAtOldCoordinate(Coordinate coordinate) throws PortletPlacementException;
142     
143 	/***
144      * Retrieve a fragment by fragment id.
145      * 
146 	 * @param fragmentId a string key for a fragment managed on this layout.
147 	 * @return The fragment associated with the given fragment id.
148 	 * @throws PortletPlacementException
149 	 */
150 	public Fragment getFragmentById(String fragmentId) throws PortletPlacementException;
151     
152     /***
153      * Takes the internal portlet placement state and writes it back
154      * out to the root fragment for the managed page layout.
155      * 
156      * @return the managed page layout with updated fragment state.
157      */
158     public Page syncPageFragments();
159         
160 }