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 relative to its current position UP one row.
45       * 
46       * @param fragment The fragment to be moved.
47       * @return new coordinate location of the portlet
48  	 * @throws PortletPlacementException
49  	 */
50  	public Coordinate moveUp(Fragment fragment) throws PortletPlacementException;
51  
52      /***
53       * Move a portlet relative to its current position DOWN one row.
54       * 
55       * @param fragment The fragment to be moved.
56       * @return new coordinate location of the portlet
57       * @throws PortletPlacementException
58       */    
59  	public Coordinate moveDown(Fragment fragment) throws PortletPlacementException;
60      
61      /***
62       * Move a portlet relative to its current position LEFT one column.
63       * 
64       * @param fragment The fragment to be moved.
65       * @return new coordinate location of the portlet
66       * @throws PortletPlacementException
67       */        
68  	public Coordinate moveLeft(Fragment fragment) throws PortletPlacementException;
69      
70      /***
71       * Move a portlet relative to its current position RIGHT one column.
72       * 
73       * @param fragment The fragment to be moved.
74       * @return new coordinate location of the portlet
75       * @throws PortletPlacementException
76       */            
77  	public Coordinate moveRight(Fragment fragment) throws PortletPlacementException;
78      
79  	/***
80       * Add a portlet to its managed page.
81       * 
82  	 * @param fragment The Fragment to add
83  	 * @param coordinate The coordinate where to place the new portlet
84  	 * @return
85  	 * @throws PortletPlacementException
86  	 */
87  	public Coordinate add(Fragment fragment, Coordinate coordinate) throws PortletPlacementException;
88      
89  	/***
90       * Remove the specified fragment.
91  	 * @param fragment
92  	 * @return
93  	 * @throws PortletPlacementException
94  	 */
95  	public Coordinate remove(Fragment fragment) throws PortletPlacementException;
96      
97      /***
98       * retrieve the number of columns for the managed layout.
99       * 
100      * @return the number of columns in the manged layout
101      * @throws PortletPlacementException
102      */
103 	public int getNumberColumns() throws PortletPlacementException;
104     
105     /***
106      * retrieve the number of rows for the managed layout at the given column.
107      * 
108      * @param column the column to retrieve the number of rows for
109      * @return the number of rows for the given column
110      * @throws PortletPlacementException
111      */    
112 	public int getNumberRows(int column) throws PortletPlacementException;
113     
114 	/***
115      * Retrieve a portlet fragment for the given coordinate.
116      *  
117 	 * @param coordinate the coordinate associated to a fragment.
118 	 * @return the fragment associated to the given coordinate
119 	 * @throws PortletPlacementException
120 	 */
121 	public Fragment getFragmentAtNewCoordinate(Coordinate coordinate) throws PortletPlacementException;
122     
123 	/***
124      * Retrieve the old portlet fragment for the given coordinate (prior to placement).
125      * 
126 	 * @param coordinate the coordinate associated to a fragment.
127 	 * @return the fragment associated to the given coordinate
128 	 * @throws PortletPlacementException
129 	 */
130 	public Fragment getFragmentAtOldCoordinate(Coordinate coordinate) throws PortletPlacementException;
131     
132 	/***
133      * Retrieve a fragment by fragment id.
134      * 
135 	 * @param fragmentId a string key for a fragment managed on this layout.
136 	 * @return The fragment associated with the given fragment id.
137 	 * @throws PortletPlacementException
138 	 */
139 	public Fragment getFragmentById(String fragmentId) throws PortletPlacementException;
140     
141     /***
142      * Takes the internal portlet placement state and writes it back
143      * out to the root fragment for the managed page layout.
144      * 
145      * @return the managed page layout with updated fragment state.
146      */
147     public Page syncPageFragments();
148         
149 }