parallel/spmd/SPMDServerInterface.java

package appl.parallel.spmd;

import java.awt.Rectangle;
import java.util.HashMap;

import edu.bonn.xulu.plugin.data.grid.GridList;
import edu.bonn.xulu.plugin.data.grid.MultiGrid;

import appl.parallel.ComputingResource;
import appl.parallel.spmd.split.DataPartition;
import appl.parallel.spmd.split.SplittableResource;

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