parallel/spmd/SPMDServerInterface.java

package appl.parallel.spmd;

import java.awt.Rectangle;

import appl.parallel.spmd.split.DataPartition;
import edu.bonn.xulu.plugin.data.grid.GridList;
import edu.bonn.xulu.plugin.data.grid.MultiGrid;

/**
 * Using this interface the programmer can access the parallel functionality on server side.
 * The programmer should subclass {@link AbstractSPMDTask} and use its method {@link AbstractSPMDTask#getSPMDServerController()} to
 * access the parallel control.
 * @author Dominik Appl
 */
public interface SPMDServerInterface {

        /**
         * Returns the base parameter with the specified id.
         *
         * @param parameterName the name of the parameter specified on client side
         * @return the base parameter
         *
         * @see SPMDClientInterface#addBaseParameter(Object, String)
         */
        public Object getBaseParameter(String parameterName);

        /**
         * Gives back the area which is actively used for read/write (in contrast
         * to neighborhood area, which is often accessed will be accessed read only).
         *
         * @param partition
         *            a partition for which the the bounds are requested
         * @return the calculation bounds in local coordinates (local means relative
         *         to the upper left corner of all available data)
         */
        public Rectangle getLocalCalculationBounds(DataPartition partition);

        /**
         * Gives back the area which is available for local access (including
         * Neighborhood)
         *
         * @param partition
         *            a partition for which the the bounds are requested
         * @return the calculation bounds in local coordinates - the upper left
         *         corner of the {@link Rectangle} will be (0,0)
         */
        public Rectangle getLocalBounds(DataPartition partition);

        /**
         * Gives back the global bounds, which are the bounds of all partitions over all servers.
         * To be clear: This are the bounds of the unsplitted data!
         * @param partition partition for which the bounds are queried
         * @return the global bounds
         */
        public Rectangle getGlobalBounds(DataPartition partition);

        /**
         * Gives back the area which is actively used for read/write (in contrast
         * to neighborhood area, which is often accessed will be accessed read only).
         *
         * @return the calculation bounds in local coordinates (local means relative
         *         to the upper left corner of all available data) of the reference
         *         resource (which is the first resource added to split-control on
         *         client side)
         *
         * @see SPMDClientController#addToSplitControl(Object, String)
         * @see SPMDClientController#setReferenceResource(Object)
         */
        public Rectangle getLocalCalculationBounds();

        /**
         * Gives back the area which is available for local access (including
         * Neighborhood)
         *
         * @return the calculation bounds in local coordinates of the reference
         *         resource (which is the first resource added to split-control on
         *         client side) - the upper left corner of the {@link Rectangle}
         *         will be (0,0)
         * @see SPMDClientController#addToSplitControl(Object, String)
         * @see SPMDClientController#setReferenceResource(Object)
         */
        public Rectangle getLocalBounds();

        /**
         * The whole {@link DataPartition} available for this task. In contrast to
         * {@link #getLocalCalculationBounds()} the neighborhood is included!
         *
         * @param name
         *            the name of the splittable
         * @return the partition of the resource which is available for local
         *         calculation
         * @see SPMDClientController#addToSplitControl(Object, String)
         */
        public DataPartition getPartition(String name);

        /**
         * Gets the array of {@link DataPartition DataPartitions} which were
         * submitted on client side via
         * {@link SPMDClientController#addToMultiDataSplitControl(Object[], String)}
         * All resources are retrieved from the data source and given back. If you
         * only need a specific resource you can use
         * {@link #getMultiPartition(String, int)} to avoid loading all data.
         *
         * @param name
         *            the name of the splittable
         * @return the partition of the resource which is available for local
         *         calculation
         * @see SPMDClientController#addToMultiDataSplitControl(Object[], String)
         * @see #getMultiPartition(String, int)
         */
        public DataPartition[] getMultiPartition(String name);

        /**
         * Gives back a MultiDataObject. A MultiDataObject can encapsulate multiple
         * objects and is especially intended for use with {@link GridList} and
         * {@link MultiGrid} types. See {@link MultiDataObject} for more details.
         *
         * @param name the name associated with the object on client side
         * @return the MDO
         */
        public MultiDataObject getMultiData(String name);

        /**
         * Gets a {@link DataPartition} which was submitted on client side via
         * {@link SPMDClientController#addToMultiDataSplitControl(Object[], String)}.
         * Only the grid with the index is returned. All other partitions are NOT
         * retrieved.
         *
         * @param name
         *            the name of the splittable
         * @param idx
         * @return the partition of the resource which is available for local
         *         calculation
         * @see SPMDClientController#addToMultiDataSplitControl(Object[], String)
         * @see #getMultiPartition(String)
         */
        public DataPartition getMultiPartition(String name, int idx);

        /**
         * Convenience method. Gets the coordinate out from the Rectangle which the
         * {@link #getLocalCalculationBounds()} returns
         *
         * @return the x-coordinate upperleft corner of the calcarea
         * @see SPMDServerController#getLocalCalculationBounds()
         * @see SPMDServerController#getLocalCalcMinX()
         * @see SPMDServerController#getLocalCalcMaxX()
         * @see SPMDServerController#getLocalCalcMinY()
         * @see SPMDServerController#getLocalCalcMaxY()
         */
        public int getLocalCalcMinX();

        /**
         * Convenience method. Gets the coordinate out from the Rectangle which the
         * {@link #getLocalCalculationBounds()} returns
         *
         * @return the y-coordinate upper left corner of the calculation area
         * @see SPMDServerController#getLocalCalculationBounds()
         * @see SPMDServerController#getLocalCalcMinX()
         * @see SPMDServerController#getLocalCalcMaxX()
         * @see SPMDServerController#getLocalCalcMinY()
         * @see SPMDServerController#getLocalCalcMaxY()
         */
        public int getLocalCalcMinY();

        /**
         * Convenience method. Gets the coordinate out from the Rectangle which the
         * {@link #getLocalCalculationBounds()} returns
         *
         * @return the x-coordinate lower right corner of the calculation area
         * @see SPMDServerController#getLocalCalculationBounds()
         * @see SPMDServerController#getLocalCalcMinX()
         * @see SPMDServerController#getLocalCalcMaxX()
         * @see SPMDServerController#getLocalCalcMinY()
         * @see SPMDServerController#getLocalCalcMaxY()
         */
        public int getLocalCalcMaxX();

        /**
         * Convenience method. Gets the coordinate out from the Rectangle which the
         * {@link #getLocalCalculationBounds()} returns
         *
         * @return the y-coordinate lower right corner of the calculation area
         * @see SPMDServerController#getLocalCalculationBounds()
         * @see SPMDServerController#getLocalCalcMinX()
         * @see SPMDServerController#getLocalCalcMaxX()
         * @see SPMDServerController#getLocalCalcMinY()
         * @see SPMDServerController#getLocalCalcMaxY()
         */
        public int getLocalCalcMaxY();

        /**
         * Removes the partition from memory. You may want to call {@link System#gc()} afterwards
         * @param name the name of the partition to remove
         */
        public void destroyPartition(String name);

        /**
         * Removes the partition from memory. You may want to call {@link System#gc()} afterwards
         * @param name the name of the multidata
         * @param idx the index of the partition to remove
         */
        public void destroyMultiPartition(String name,int idx);
}
1	package appl.parallel.spmd;
2
3	import java.awt.Rectangle;
4
5	import appl.parallel.spmd.split.DataPartition;
6	import edu.bonn.xulu.plugin.data.grid.GridList;
7	import edu.bonn.xulu.plugin.data.grid.MultiGrid;
8
9	/**
10	* Using this interface the programmer can access the parallel functionality on server side.
11	* The programmer should subclass {@link AbstractSPMDTask} and use its method {@link AbstractSPMDTask#getSPMDServerController()} to
12	* access the parallel control.
13	* @author Dominik Appl
14	*/
15	public interface SPMDServerInterface {
16
17	/**
18	* Returns the base parameter with the specified id.
19	*
20	* @param parameterName the name of the parameter specified on client side
21	* @return the base parameter
22	*
23	* @see SPMDClientInterface#addBaseParameter(Object, String)
24	*/
25	public Object getBaseParameter(String parameterName);
26
27	/**
28	* Gives back the area which is actively used for read/write (in contrast
29	* to neighborhood area, which is often accessed will be accessed read only).
30	*
31	* @param partition
32	* a partition for which the the bounds are requested
33	* @return the calculation bounds in local coordinates (local means relative
34	* to the upper left corner of all available data)
35	*/
36	public Rectangle getLocalCalculationBounds(DataPartition partition);
37
38	/**
39	* Gives back the area which is available for local access (including
40	* Neighborhood)
41	*
42	* @param partition
43	* a partition for which the the bounds are requested
44	* @return the calculation bounds in local coordinates - the upper left
45	* corner of the {@link Rectangle} will be (0,0)
46	*/
47	public Rectangle getLocalBounds(DataPartition partition);
48
49	/**
50	* Gives back the global bounds, which are the bounds of all partitions over all servers.
51	* To be clear: This are the bounds of the unsplitted data!
52	* @param partition partition for which the bounds are queried
53	* @return the global bounds
54	*/
55	public Rectangle getGlobalBounds(DataPartition partition);
56
57	/**
58	* Gives back the area which is actively used for read/write (in contrast
59	* to neighborhood area, which is often accessed will be accessed read only).
60	*
61	* @return the calculation bounds in local coordinates (local means relative
62	* to the upper left corner of all available data) of the reference
63	* resource (which is the first resource added to split-control on
64	* client side)
65	*
66	* @see SPMDClientController#addToSplitControl(Object, String)
67	* @see SPMDClientController#setReferenceResource(Object)
68	*/
69	public Rectangle getLocalCalculationBounds();
70
71	/**
72	* Gives back the area which is available for local access (including
73	* Neighborhood)
74	*
75	* @return the calculation bounds in local coordinates of the reference
76	* resource (which is the first resource added to split-control on
77	* client side) - the upper left corner of the {@link Rectangle}
78	* will be (0,0)
79	* @see SPMDClientController#addToSplitControl(Object, String)
80	* @see SPMDClientController#setReferenceResource(Object)
81	*/
82	public Rectangle getLocalBounds();
83
84	/**
85	* The whole {@link DataPartition} available for this task. In contrast to
86	* {@link #getLocalCalculationBounds()} the neighborhood is included!
87	*
88	* @param name
89	* the name of the splittable
90	* @return the partition of the resource which is available for local
91	* calculation
92	* @see SPMDClientController#addToSplitControl(Object, String)
93	*/
94	public DataPartition getPartition(String name);
95
96	/**
97	* Gets the array of {@link DataPartition DataPartitions} which were
98	* submitted on client side via
99	* {@link SPMDClientController#addToMultiDataSplitControl(Object[], String)}
100	* All resources are retrieved from the data source and given back. If you
101	* only need a specific resource you can use
102	* {@link #getMultiPartition(String, int)} to avoid loading all data.
103	*
104	* @param name
105	* the name of the splittable
106	* @return the partition of the resource which is available for local
107	* calculation
108	* @see SPMDClientController#addToMultiDataSplitControl(Object[], String)
109	* @see #getMultiPartition(String, int)
110	*/
111	public DataPartition[] getMultiPartition(String name);
112
113	/**
114	* Gives back a MultiDataObject. A MultiDataObject can encapsulate multiple
115	* objects and is especially intended for use with {@link GridList} and
116	* {@link MultiGrid} types. See {@link MultiDataObject} for more details.
117	*
118	* @param name the name associated with the object on client side
119	* @return the MDO
120	*/
121	public MultiDataObject getMultiData(String name);
122
123	/**
124	* Gets a {@link DataPartition} which was submitted on client side via
125	* {@link SPMDClientController#addToMultiDataSplitControl(Object[], String)}.
126	* Only the grid with the index is returned. All other partitions are NOT
127	* retrieved.
128	*
129	* @param name
130	* the name of the splittable
131	* @param idx
132	* @return the partition of the resource which is available for local
133	* calculation
134	* @see SPMDClientController#addToMultiDataSplitControl(Object[], String)
135	* @see #getMultiPartition(String)
136	*/
137	public DataPartition getMultiPartition(String name, int idx);
138
139	/**
140	* Convenience method. Gets the coordinate out from the Rectangle which the
141	* {@link #getLocalCalculationBounds()} returns
142	*
143	* @return the x-coordinate upperleft corner of the calcarea
144	* @see SPMDServerController#getLocalCalculationBounds()
145	* @see SPMDServerController#getLocalCalcMinX()
146	* @see SPMDServerController#getLocalCalcMaxX()
147	* @see SPMDServerController#getLocalCalcMinY()
148	* @see SPMDServerController#getLocalCalcMaxY()
149	*/
150	public int getLocalCalcMinX();
151
152	/**
153	* Convenience method. Gets the coordinate out from the Rectangle which the
154	* {@link #getLocalCalculationBounds()} returns
155	*
156	* @return the y-coordinate upper left corner of the calculation area
157	* @see SPMDServerController#getLocalCalculationBounds()
158	* @see SPMDServerController#getLocalCalcMinX()
159	* @see SPMDServerController#getLocalCalcMaxX()
160	* @see SPMDServerController#getLocalCalcMinY()
161	* @see SPMDServerController#getLocalCalcMaxY()
162	*/
163	public int getLocalCalcMinY();
164
165	/**
166	* Convenience method. Gets the coordinate out from the Rectangle which the
167	* {@link #getLocalCalculationBounds()} returns
168	*
169	* @return the x-coordinate lower right corner of the calculation area
170	* @see SPMDServerController#getLocalCalculationBounds()
171	* @see SPMDServerController#getLocalCalcMinX()
172	* @see SPMDServerController#getLocalCalcMaxX()
173	* @see SPMDServerController#getLocalCalcMinY()
174	* @see SPMDServerController#getLocalCalcMaxY()
175	*/
176	public int getLocalCalcMaxX();
177
178	/**
179	* Convenience method. Gets the coordinate out from the Rectangle which the
180	* {@link #getLocalCalculationBounds()} returns
181	*
182	* @return the y-coordinate lower right corner of the calculation area
183	* @see SPMDServerController#getLocalCalculationBounds()
184	* @see SPMDServerController#getLocalCalcMinX()
185	* @see SPMDServerController#getLocalCalcMaxX()
186	* @see SPMDServerController#getLocalCalcMinY()
187	* @see SPMDServerController#getLocalCalcMaxY()
188	*/
189	public int getLocalCalcMaxY();
190
191	/**
192	* Removes the partition from memory. You may want to call {@link System#gc()} afterwards
193	* @param name the name of the partition to remove
194	*/
195	public void destroyPartition(String name);
196
197	/**
198	* Removes the partition from memory. You may want to call {@link System#gc()} afterwards
199	* @param name the name of the multidata
200	* @param idx the index of the partition to remove
201	*/
202	public void destroyMultiPartition(String name,int idx);
203	}