Grid2D


1   package org.jahia.layout;
2   
3   /**
4    * This class represents a dynamic 2D grid in which we can store objects. This
5    * is an alternative to using arrays, allowing us to be able to add and remove
6    * rows at columns from the grid. These grids are always rectangular, meaning
7    * that every line has the same length.
8    *
9    * This class may also be used to build size-limited grids, that are defined
10   * by using the second constructor. This is recommended in cases where we want
11   * to be sure we never build a grid that is bigger than a certain size (also
12   * useful for debugging purposes :))
13   *
14   * This implementation uses Vectors of Vectors to represent the grid. If
15   * performance becomes an issue we might want to look into other ways of
16   * representing the grid. It is anticipated though that we will be adding rows
17   * and columns often, and there for this solution seems to be better fitted than
18   * using two dimensionnal arrays, which would need to be copied in order to be
19   * enlarged.
20   *
21   * Title:        Jahia
22   * Description:  Jahia Portal Server
23   * Copyright:    Copyright (c) 2002
24   * Company:      Jahia Ltd
25   * @author Serge Huber
26   * @version 1.0
27   */
28  import java.util.Vector  ;
29  
30  public class Grid2D {
31      /**
32       * @associates Vector
33       */
34      private Vector   rowList = new Vector  ();
35      private int rowCount = 0;
36      private int columnCount = 0;
37      // The following values are used to limit the maximum size of the grid if
38      // they are set to positive values.
39      private int maxRows = -1;
40      private int maxColumns = -1;
41  
42      /**
43       * This inner class is only used to tag grid entries so that we may
44       * recognize them as empty
45       */
46      private class DummyGridEmptyObject {
47      }
48  
49      /**
50       * Not much to say here, just a standard constructor
51       */
52      public Grid2D() {
53      }
54  
55      /**
56       * This constructor allows a construction of a grid with limited maximum
57       * size.
58       * @param maxRowCount specifies the maximum row size of the grid
59       * @param maxColumnCount specifies the maximum column size of the grid
60       */
61      public Grid2D(int maxRowCount, int maxColumnCount) {
62          maxRows = maxRowCount;
63          maxColumns = maxColumnCount;
64      }
65  
66      /**
67       * Returns the number of rows in the grid
68       * @returns an integer representing the number of rows in the grid :)
69       */
70      public int getRowCount() {
71          return rowCount;
72      }
73  
74      /**
75       * Returns the number of columns in the grid
76       * @returns an integer representing the number of columns in the grid :)
77       */
78      public int getColumnCount() {
79          return columnCount;
80      }
81  
82      /**
83       * Adds a number of empty rows to the grid. This is designed for internal
84       * use only.
85       * @param numberOfRows an integer specifying the number of rows to add to
86       * the function.
87       * @exception ArrayIndexOutOfBoundsException thrown if the number of rows to
88       * be added would make the grid cross the maximum number of rows boundary.
89       * In this case NO rows are added at all.
90       */
91      private void addRows(int numberOfRows)
92      throws ArrayIndexOutOfBoundsException   {
93          if (maxRows >= 0) {
94              if (rowCount + numberOfRows > maxRows) {
95                  throw new ArrayIndexOutOfBoundsException  ("Grid2D.addRows : number of rows to add would exceed maximum number of rows !");
96              }
97          }
98          for (int i=0; i < numberOfRows; i++) {
99              Vector   curVector = new Vector  ();
100             // we insert a simple object, to be replaced later by a real value.
101             for (int j=0; j < columnCount; j++) {
102                 curVector.add(new DummyGridEmptyObject());
103             }
104             rowList.add(curVector);
105         }
106         rowCount += numberOfRows;
107     }
108 
109     /**
110      * Adds a number of empty columns to the grid. This is designed for internal
111      * use only.
112      * @param numberOfColumns an integer specifying the number of columns to be
113      * added.
114      * @exception ArrayIndexOutOfBoundsException thrown if the number of columns
115      * to be added would make the grid cross the maximum number of columns
116      * boundary. In this case NO rows are added at all.
117      */
118     private void addColumns(int numberOfColumns)
119     throws ArrayIndexOutOfBoundsException   {
120         if (maxColumns >= 0) {
121             if (columnCount + numberOfColumns > maxColumns) {
122                 throw new ArrayIndexOutOfBoundsException  ("Grid2D.addColumns : number of columns to add would exceed maximum number of columns !");
123             }
124         }
125         // for each row, let's add an entry to the vector in it.
126         for (int i=0; i < rowCount; i++) {
127             Vector   curVector = (Vector  ) rowList.elementAt(i);
128             // we insert a simple object, to be replaced later by a real value.
129             for (int j=0; j < numberOfColumns; j++) {
130                 curVector.add(new DummyGridEmptyObject());
131             }
132         }
133         columnCount += numberOfColumns;
134     }
135 
136     /**
137      * Returns the object at the specified grid position.
138      * @param row an integer (0-based) representing the row at which we want to
139      * recuperate the object
140      * @param column an integer (0-based) representing the column at which we
141      * want to recuperate the object
142      * @returns the object at the specified coordinates. If there is no object,
143      * null is returned.
144      * @exception ArrayIndexOutOfBoundsException thrown if the row or column
145      * coordinates are invalid
146      */
147     public Object   getElementAt(int row, int column)
148     throws ArrayIndexOutOfBoundsException   {
149         if ((row < 0) || (row >= rowCount) ) {
150             throw new ArrayIndexOutOfBoundsException   ("Grid2D.elementAt : row value " +
151                                                       Integer.toString(row) +
152                                                       " is invalid ! (rowCount=" +
153                                                       Integer.toString(rowCount) + ")");
154         }
155         if ((column < 0) || (column >= columnCount) ) {
156             throw new ArrayIndexOutOfBoundsException   ("Grid2D.elementAt : column value " +
157                                                       Integer.toString(column) +
158                                                       " is invalid ! (rowCount=" +
159                                                       Integer.toString(rowCount) + ")");
160         }
161         Vector   rowVector = (Vector  ) rowList.elementAt(row);
162         Object   theObject = rowVector.elementAt(column);
163         if (theObject instanceof DummyGridEmptyObject) {
164             return null;
165         } else {
166             return theObject;
167         }
168     }
169 
170     /**
171      * Set the grid position at the specified coordinates at the value specified
172      * by the object. If the value of the coordinates are out of the current
173      * grid size and are positive, the size of the grid is extended to allow
174      * this position to be valid.
175      * WARNING : if invalid positions or random values are passed here, this
176      * data structure may become dangerously large !
177      *
178      * @param row an integer (0-based) specifying the row at which to set the
179      * object
180      * @param column an integer (0-based) specifying the column at which to set
181      * the object
182      * @param theObject the actual value to be set at the specified coordinates
183      * @exception ArrayIndexOutOfBoundsException thrown if the coordinates are
184      * larger than the maximum number of rows and columns allowed. In this case
185      * the grid is not modified at all.
186      */
187     public void setElementAt(int row, int column, Object   theObject)
188     throws ArrayIndexOutOfBoundsException   {
189         // first let's test if we must enlarge the grid...
190         if ( (row+1) > rowCount ) {
191             addRows(row+1-rowCount);
192         }
193         if ( (column+1) > columnCount ) {
194             addColumns(column+1-columnCount);
195         }
196         // we may now set the value of the object.
197         Vector   rowVector = (Vector  ) rowList.elementAt(row);
198         rowVector.setElementAt(theObject, column);
199     }
200 
201     /**
202      * Sets an empty element at the position specified, creating the new
203      * rows and columns if necessary.
204      * @param row
205      * @param column
206      *
207      * @see setElementAt
208      */
209     public void setEmptyElementAt(int row, int column) {
210         setElementAt(row, column, new DummyGridEmptyObject() );
211     }
212 
213     /**
214      * Empties the grid of all it's contents.
215      */
216     public void clear() {
217         rowList.clear();
218         rowList = null;
219         rowList = new Vector  ();
220         rowCount = 0;
221         columnCount = 0;
222     }
223 
224     /**
225      * Converts the internal structure to a grid. This is done by calling the
226      * toString method of each object, and insertion newline characters after
227      * each row in the grid...
228      * @returns a String containing the grid's output seperated by newline
229      * characters...
230      */
231     public String   toString() {
232         StringBuffer   result = new StringBuffer  ("");
233         for (int i = 0; i < getRowCount() ; i++) {
234             for (int j = 0; j < getColumnCount(); j++) {
235                 Object   curObject = getElementAt(i, j);
236                 if (curObject == null) {
237                     result.append("<null>");
238                 } else {
239                     result.append(curObject.toString());
240                 }
241                 result.append(" ");
242             }
243             result.append('\n');
244         }
245         return result.toString();
246     }
247 
248 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags