View Javadoc

1   /*
2    * Copyright (C) 2004 Christian Siefkes <christian@siefkes.net>.
3    * Development of this software is supported by the German Research Society,
4    * Berlin-Brandenburg Graduate School in Distributed Information Systems
5    * (DFG grant no. GRK 316).
6    *
7    * This library is free software; you can redistribute it and/or
8    * modify it under the terms of the GNU Lesser General Public
9    * License as published by the Free Software Foundation; either
10   * version 2.1 of the License, or (at your option) any later version.
11   *
12   * This library is distributed in the hope that it will be useful,
13   * but WITHOUT ANY WARRANTY; without even the implied warranty of
14   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15   * Lesser General Public License for more details.
16   *
17   * You should have received a copy of the GNU Lesser General Public
18   * License along with this library; if not, visit
19   * http://www.gnu.org/licenses/lgpl.html or write to the Free Software
20   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
21   */
22  package de.fu_berlin.ties.combi;
23  
24  import org.apache.commons.lang.builder.EqualsBuilder;
25  import org.apache.commons.lang.builder.HashCodeBuilder;
26  import org.apache.commons.lang.builder.ToStringBuilder;
27  
28  /***
29   * Immutable class contains state information used by
30   * {@linkplain de.fu_berlin.ties.combi.CombinationStrategy combination
31   * strategies}.
32   *
33   * @author Christian Siefkes
34   * @version $Revision: 1.5 $, $Date: 2004/07/15 14:35:48 $, $Author: siefkes $
35   */
36  public class CombinationState {
37  
38      /***
39       * Combination state to be used for outside/other (type is set to
40       * <code>null</code>). Begin and end are always <code>false</code>.
41       */
42      public static final CombinationState OUTSIDE =
43          new CombinationState(null, false, false);
44  
45      /***
46       * The type (class) of the current instance; or <code>null</code> if we're
47       * outside of any instance ({@link #OUTSIDE}).
48       */
49      private final String type;
50  
51      /***
52       * Whether this is the begin of an instance.
53       */
54      private final boolean begin;
55  
56      /***
57       * Whether this is the end of an instance.
58       */
59      private final boolean end;
60  
61      /***
62       * Signals that the extraction in progress during the <em>preceding</em>
63       * combination state should be discarded. If this combination state starts
64       * a new extraction, the new extraction should <em>not</em> be discarded.
65       */
66      private final boolean discardPreceding;
67  
68      /***
69       * Creates a new instance, setting {@link #isDiscardPreceding()} to
70       * <code>false</code>.
71       *
72       * @param myType the type (class) of this instance; or <code>null</code> if
73       * we're outside of any instance
74       * @param myBegin whether this is the begin of an instance
75       * @param myEnd whether this is the end of an instance
76       */
77      public CombinationState(final String myType, final boolean myBegin,
78              final boolean myEnd) {
79          this(myType, myBegin, myEnd, false);
80      }
81  
82      /***
83       * Creates a new instance.
84       *
85       * @param myType the type (class) of this instance; or <code>null</code> if
86       * we're outside of any instance
87       * @param myBegin whether this is the begin of an instance
88       * @param myEnd whether this is the end of an instance
89       * @param discardPrevious whether the extraction in progress during the
90       * <em>preceding</em> combination state should be discarded
91       */
92      public CombinationState(final String myType, final boolean myBegin,
93              final boolean myEnd, final boolean discardPrevious) {
94          super();
95          type = myType;
96          begin = myBegin;
97          end = myEnd;
98          discardPreceding = discardPrevious;
99      }
100 
101     /***
102      * Indicates whether some other object is "equal to" this one, fulfulling
103      * the {@link Object#equals(java.lang.Object)} contract.
104      *
105      * @param obj the reference object with which to compare
106      * @return <code>true</code> iff the specified object is a
107      * {@link CombinationState} equal to this instance
108      */
109     public boolean equals(final Object obj) {
110         if (obj == this) {
111             return true;
112         } else if ((obj != null) && (getClass().equals(obj.getClass()))) {
113             // used getClass instead of instanceof because otherwise subclasses
114             // with additional fields would break the contract
115             final CombinationState other = (CombinationState) obj;
116             return new EqualsBuilder()
117                 .append(type, other.type)
118                 .append(begin, other.begin)
119                 .append(end, other.end)
120                 .append(discardPreceding, other.discardPreceding)
121                 .isEquals();
122         } else {
123             return false;
124         }
125     }
126 
127     /***
128      * Returns the type (class) of the current instance; or <code>null</code>
129      * if we're outside of any instance ({@link #OUTSIDE}).
130      *
131      * @return the value of the attribute
132      */
133     public String getType() {
134         return type;
135     }
136 
137     /***
138      * Returns a hash code value for this object, fulfulling the
139      * {@link Object#hashCode()} contract.
140      *
141      * @return a hash code value for this object
142      */
143     public int hashCode() {
144         // you pick two hard-coded, randomly chosen, non-zero, odd numbers
145         // (preferably primes); ideally different for each class
146         return new HashCodeBuilder(29, 31)
147             .append(type)
148             .append(begin)
149             .append(end)
150             .append(discardPreceding)
151             .toHashCode();
152     }
153 
154     /***
155      * Returns whether this is the begin of an instance.
156      * @return the value of the attribute
157      */
158     public boolean isBegin() {
159         return begin;
160     }
161 
162     /***
163      * Signals that the extraction in progress during the <em>preceding</em>
164      * combination state should be discarded. If this combination state starts
165      * a new extraction, the new extraction should <em>not</em> be discarded.
166      *
167      * @return the value of the attribute
168      */
169     public boolean isDiscardPreceding() {
170         return discardPreceding;
171     }
172 
173     /***
174      * Returns whether this is the end of an instance.
175      * @return the value of the attribute
176      */
177     public boolean isEnd() {
178         return end;
179     }
180 
181     /***
182      * Returns a string representation of this object.
183      *
184      * @return a textual representation
185      */
186     public String toString() {
187         return new ToStringBuilder(this)
188             .append("type", type)
189             .append("begin", begin)
190             .append("end", end)
191             .append("discard preceding", discardPreceding)
192             .toString();
193     }
194 
195 }