View Javadoc

1   // START LICENSE
2   // JSet - a Java JSet card board game implementation
3   // Copyright (C) 2004 Jerome Lacoste
4   //
5   // This program is free software; you can redistribute it and/or modify
6   // it under the terms of the GNU General Public License as published by
7   // the Free Software Foundation; either version 2 of the License, or (at
8   // your option) any later version.
9   //
10  // This program is distributed in the hope that it will be useful, but
11  // WITHOUT ANY WARRANTY; without even the implied warranty of
12  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13  // General Public License for more details.
14  //
15  // You should have received a copy of the GNU General Public License
16  // along with this program; if not, write to the Free Software
17  // Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
18  // END LICENSE
19  
20  package org.cb.cardboard;
21  
22  import java.util.EventObject;
23  import java.util.List;
24  import java.io.Serializable;
25  
26  /***
27   * An event for a CardBoard.
28   *
29   * @author jerome@coffeebreaks.org - last modified by $LastModifiedBy$
30   * @version $Id: CardBoardEvent.java 129 2004-04-15 05:00:43Z jerome $
31   */
32  public class CardBoardEvent extends EventObject
33  {
34    /***
35     * Identifies one or more changes in the lists contents.
36     */
37    public static final int CONTENTS_CHANGED = 0;
38    /***
39     * Identifies the addition of one or more contiguous items to the list.
40     */
41    public static final int INTERVAL_ADDED = 1;
42    /***
43     * Identifies the removal of one or more contiguous items from the list.
44     */
45    public static final int INTERVAL_REMOVED = 2;
46  
47    private final int _type;
48    private final BoardIndexes _boardIndexes;
49  
50    /***
51     * A supertype tag for the different indexes implementation.
52     * @see CardBoardEvent.IndexInterval
53     * @see CardBoardEvent.IndexList
54     */
55    public static interface BoardIndexes extends Serializable
56    {
57    }
58  
59    /***
60     * A class that allows to specify BoardIndexes as an interval between two indexes.
61     */
62    public static final class IndexInterval implements BoardIndexes
63    {
64      private final int _index0;
65      private final int _index1;
66  
67      /***
68       * Creates an instance of IndexInterval given the two specified index boundaries.
69       * @param index0
70       * @param index1
71       * @throws IllegalArgumentException if <code>index0 > index1</code>
72       */
73      private IndexInterval(final int index0, final int index1)
74      {
75        if (index0 > index1)
76        {
77          throw new IllegalArgumentException("_index0=" + index0 + " > _index1=" + index1);
78        }
79        this._index0 = index0;
80        this._index1 = index1;
81      }
82  
83      /***
84       * @return the lower bound of the index interval
85       */
86      public int getIndex0()
87      {
88        return _index0;
89      }
90  
91      /***
92       * @return the higher bound of the index interval
93       */
94      public int getIndex1()
95      {
96        return _index1;
97      }
98  
99      /***
100      * Returns a string representation of this IndexInterval. This method
101      * is intended to be used only for debugging purposes, and the
102      * content and format of the returned string may vary between
103      * implementations. The returned string may be empty but may not
104      * be <code>null</code>.
105      *
106      * @return a string representation of this IndexInterval.
107      */
108     public String toString()
109     {
110       return _index0 + "-" + _index1;
111     }
112   }
113 
114   /***
115    * A class that allows to specify BoardIndexes as a list of indexes.
116    */
117   public static final class IndexList implements BoardIndexes
118   {
119     private final List _indexesInBoard;
120 
121     /***
122      * Creates an instance given the specified list of indexes.
123      * @param indexesInBoard a <code>List</code> of <code>Integer</code>s.
124      */
125     private IndexList(final List indexesInBoard)
126     {
127       _indexesInBoard = indexesInBoard;
128     }
129 
130     /***
131      * Returns the list of indexes on the board.
132      * @return a <code>List</code> of <code>Integer</code>s.
133      */
134     public List getIndexesInBoard()
135     {
136       return _indexesInBoard;
137     }
138     /***
139      * Returns a string representation of this IndexInterval. This method
140      * is intended to be used only for debugging purposes, and the
141      * content and format of the returned string may vary between
142      * implementations. The returned string may be empty but may not
143      * be <code>null</code>.
144      *
145      * @return a string representation of this IndexInterval.
146      */
147     public String toString()
148     {
149       final StringBuffer buf = new StringBuffer();
150       for (int i = 0; i < _indexesInBoard.size(); i++)
151       {
152         final Integer integer = (Integer) _indexesInBoard.get(i);
153         if (i > 0)
154         {
155           buf.append(",");
156         }
157         buf.append(integer.intValue());
158       }
159       return buf.toString();
160     }
161   }
162 
163   /***
164    * Returns the event _type. The possible values are:
165    * <ul>
166    * <li> {@link #CONTENTS_CHANGED}
167    * <li> {@link #INTERVAL_ADDED}
168    * <li> {@link #INTERVAL_REMOVED}
169    * </ul>
170    *
171    * @return an int representing the _type value
172    */
173   public int getType()
174   {
175     return _type;
176   }
177 
178 
179   /***
180    * Return the indexes of the cards modified on the board.
181    * Can be an instance of {@link IndexInterval range} or a {@link
182    * IndexList list of indexes}.
183    * @return the board indexes
184    */
185   public BoardIndexes getBoardIndexes()
186   {
187     return _boardIndexes;
188   }
189 
190   /***
191    * Constructs a CardBoardEvent object.
192    *
193    * @param source the source Object (typically <code>this</code>)
194    * @param type   an int specifying {@link #INTERVAL_ADDED}, or {@link #INTERVAL_REMOVED}
195    * @param index0 an int specifying the bottom of a range
196    * @param index1 an int specifying the top of a range
197    * @throws IllegalArgumentException if {@link #CONTENTS_CHANGED} is specified as _type.
198    */
199   public CardBoardEvent(final Object source, final int type, final int index0, final int index1)
200   {
201     super(source);
202     if (type == CONTENTS_CHANGED)
203     {
204       final String s = "CONTENTS_CHANGED type not allowed when specifying an interval.";
205       throw new IllegalArgumentException(s);
206     }
207     this._type = type;
208     this._boardIndexes = new IndexInterval(index0, index1);
209   }
210 
211   /***
212    * Constructs a CardBoardEvent object.
213    *
214    * @param source the source Object (typically <code>this</code>)
215    * @param indexes a List of Integer int specifying the indexes changed.
216    */
217   public CardBoardEvent(final Object source, final List indexes)
218   {
219     super(source);
220     this._type = CONTENTS_CHANGED;
221     // FIXME we should copy that list and make it immutable
222     this._boardIndexes = new IndexList(indexes);
223   }
224 
225   /***
226    * Returns a string representation of this CardBoardEvent. This method
227    * is intended to be used only for debugging purposes, and the
228    * content and format of the returned string may vary between
229    * implementations. The returned string may be empty but may not
230    * be <code>null</code>.
231    *
232    * @return a string representation of this CardBoardEvent.
233    * @since 1.4
234    */
235   public String toString()
236   {
237     return getClass().getName()
238          + "[_type=" + _type
239          + ",{indexes=" + _boardIndexes + "}]";
240   }
241 }