View Javadoc

1   /*
2    * Copyright (C) 2004-2006 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 program is free software; you can redistribute it and/or modify
8    * it under the terms of the GNU General Public License as published by
9    * the Free Software Foundation; either version 2 of the License, or
10   * (at your option) any later version.
11   *
12   * This program 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
15   * GNU General Public License for more details.
16   *
17   * You should have received a copy of the GNU General Public License
18   * along with this program; if not, visit
19   * http://www.gnu.org/licenses/gpl.html or write to the Free Software
20   * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  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  import de.fu_berlin.ties.classify.Probability;
29  
30  /***
31   * Immutable class contains state information used by
32   * {@linkplain de.fu_berlin.ties.combi.CombinationStrategy combination
33   * strategies}.
34   *
35   * @author Christian Siefkes
36   * @version $Revision: 1.9 $, $Date: 2006/10/21 16:04:01 $, $Author: siefkes $
37   */
38  public class CombinationState {
39  
40      /***
41       * Combination state to be used for outside/other (type is set to
42       * <code>null</code>). Begin and end are always <code>false</code>,
43       * probability is <code>null</code>.
44       */
45      public static final CombinationState OUTSIDE =
46          new CombinationState(null, false, false, null);
47  
48      /***
49       * The type (class) of the current instance; or <code>null</code> if we're
50       * outside of any instance ({@link #OUTSIDE}).
51       */
52      private final String type;
53  
54      /***
55       * Whether this is the begin of an instance.
56       */
57      private final boolean begin;
58  
59      /***
60       * Whether this is the end of an instance.
61       */
62      private final boolean end;
63  
64      /***
65       * Signals that the extraction in progress during the <em>preceding</em>
66       * combination state should be discarded. If this combination state starts
67       * a new extraction, the new extraction should <em>not</em> be discarded.
68       */
69      private final boolean discardPreceding;
70  
71      /***
72       * The probability of this state; or <code>null</code> if
73       * unknown/unspecified.
74       */
75      private final Probability probability;
76  
77      /***
78       * Creates a new instance, setting {@link #isDiscardPreceding()} to
79       * <code>false</code>.
80       *
81       * @param myType the type (class) of this instance; or <code>null</code> if
82       * we're outside of any instance
83       * @param myBegin whether this is the begin of an instance
84       * @param myEnd whether this is the end of an instance
85       * @param myProb the probability of this state; or <code>null</code> if
86       * unknown/unspecified
87       */
88      public CombinationState(final String myType, final boolean myBegin,
89              final boolean myEnd, final Probability myProb) {
90          this(myType, myBegin, myEnd, myProb, false);
91      }
92  
93      /***
94       * Creates a new instance.
95       *
96       * @param myType the type (class) of this instance; or <code>null</code> if
97       * we're outside of any instance
98       * @param myBegin whether this is the begin of an instance
99       * @param myEnd whether this is the end of an instance
100      * @param myProb the probability of this state; or <code>null</code> if
101      * unknown/unspecified
102      * @param discardPrevious whether the extraction in progress during the
103      * <em>preceding</em> combination state should be discarded
104      */
105     public CombinationState(final String myType, final boolean myBegin,
106             final boolean myEnd, final Probability myProb,
107             final boolean discardPrevious) {
108         super();
109         type = myType;
110         begin = myBegin;
111         end = myEnd;
112         probability = myProb;
113         discardPreceding = discardPrevious;
114     }
115 
116     /***
117      * Indicates whether some other object is "equal to" this one, fulfulling
118      * the {@link Object#equals(java.lang.Object)} contract.
119      *
120      * @param obj the reference object with which to compare
121      * @return <code>true</code> iff the specified object is a
122      * {@link CombinationState} equal to this instance
123      */
124     public boolean equals(final Object obj) {
125         if (obj == this) {
126             return true;
127         } else if ((obj != null) && (getClass().equals(obj.getClass()))) {
128             // used getClass instead of instanceof because otherwise subclasses
129             // with additional fields would break the contract
130             final CombinationState other = (CombinationState) obj;
131             return new EqualsBuilder()
132                 .append(type, other.type)
133                 .append(begin, other.begin)
134                 .append(end, other.end)
135                 .append(discardPreceding, other.discardPreceding)
136                 .isEquals();
137         } else {
138             return false;
139         }
140     }
141 
142     /***
143      * Returns the probability of this instance.
144      * @return the value of the attribute, or <code>null</code> if
145      * unknown/unspecified
146      */
147 
148     public Probability getProbability() {
149         return probability;
150     }
151 
152     /***
153      * Returns the type (class) of the current instance; or <code>null</code>
154      * if we're outside of any instance ({@link #OUTSIDE}).
155      *
156      * @return the value of the attribute
157      */
158     public String getType() {
159         return type;
160     }
161 
162     /***
163      * Returns a hash code value for this object, fulfulling the
164      * {@link Object#hashCode()} contract.
165      *
166      * @return a hash code value for this object
167      */
168     public int hashCode() {
169         // you pick two hard-coded, randomly chosen, non-zero, odd numbers
170         // (preferably primes); ideally different for each class
171         return new HashCodeBuilder(29, 31)
172             .append(type)
173             .append(begin)
174             .append(end)
175             .append(discardPreceding)
176             .toHashCode();
177     }
178 
179     /***
180      * Returns whether this is the begin of an instance.
181      * @return the value of the attribute
182      */
183     public boolean isBegin() {
184         return begin;
185     }
186 
187     /***
188      * Signals that the extraction in progress during the <em>preceding</em>
189      * combination state should be discarded. If this combination state starts
190      * a new extraction, the new extraction should <em>not</em> be discarded.
191      *
192      * @return the value of the attribute
193      */
194     public boolean isDiscardPreceding() {
195         return discardPreceding;
196     }
197 
198     /***
199      * Returns whether this is the end of an instance.
200      * @return the value of the attribute
201      */
202     public boolean isEnd() {
203         return end;
204     }
205 
206     /***
207      * Returns a string representation of this object.
208      *
209      * @return a textual representation
210      */
211     public String toString() {
212         final ToStringBuilder builder = new ToStringBuilder(this)
213             .append("type", type)
214             .append("begin", begin)
215             .append("end", end)
216             .append("discard preceding", discardPreceding);
217         if (probability != null) {
218             builder.append("probability", probability);
219         }
220         return builder.toString();
221     }
222 
223 }