KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > jface > bindings > TriggerSequence


1 /*******************************************************************************
2  * Copyright (c) 2004, 2006 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/
11 package org.eclipse.jface.bindings;
12
13 import org.eclipse.jface.util.Util;
14
15 /**
16  * <p>
17  * A sequence of one or more triggers. None of these triggers may be
18  * <code>null</code>.
19  * </p>
20  *
21  * @since 3.1
22  */
23 public abstract class TriggerSequence {
24     
25     /**
26      * The value to see that hash code to if the hash code is not yet computed.
27      */
28     private static final int HASH_CODE_NOT_COMPUTED = -1;
29
30     /**
31      * A factor for computing the hash code for all trigger sequences.
32      */
33     private static final int HASH_FACTOR = 89;
34
35     /**
36      * An internal constant used only in this object's hash code algorithm.
37      */
38     private static final int HASH_INITIAL = TriggerSequence.class.getName()
39             .hashCode();
40
41     /**
42      * The hash code for this object. This value is computed lazily, and marked
43      * as invalid when one of the values on which it is based changes. This
44      * values is <code>HASH_CODE_NOT_COMPUTED</code> iff the hash code has not
45      * yet been computed.
46      */
47     protected transient int hashCode = HASH_CODE_NOT_COMPUTED;
48
49     /**
50      * The list of trigger in this sequence. This value is never
51      * <code>null</code>, and never contains <code>null</code> elements.
52      */
53     protected final Trigger[] triggers;
54
55     /**
56      * Constructs a new instance of <code>TriggerSequence</code>.
57      *
58      * @param triggers
59      * The triggers contained within this sequence; must not be
60      * <code>null</code> or contain <code>null</code> elements.
61      * May be empty.
62      */
63     public TriggerSequence(final Trigger[] triggers) {
64         if (triggers == null) {
65             throw new NullPointerException JavaDoc("The triggers cannot be null"); //$NON-NLS-1$
66 }
67
68         for (int i = 0; i < triggers.length; i++) {
69             if (triggers[i] == null) {
70                 throw new IllegalArgumentException JavaDoc(
71                         "All triggers in a trigger sequence must be an instance of Trigger"); //$NON-NLS-1$
72 }
73         }
74
75         final int triggerLength = triggers.length;
76         this.triggers = new Trigger[triggerLength];
77         System.arraycopy(triggers, 0, this.triggers, 0, triggerLength);
78     }
79
80     /**
81      * Returns whether or not this key sequence ends with the given key
82      * sequence.
83      *
84      * @param triggerSequence
85      * a trigger sequence. Must not be <code>null</code>.
86      * @param equals
87      * whether or not an identical trigger sequence should be
88      * considered as a possible match.
89      * @return <code>true</code>, iff the given trigger sequence ends with
90      * this trigger sequence.
91      */
92     public final boolean endsWith(final TriggerSequence triggerSequence,
93             final boolean equals) {
94         if (triggerSequence == null) {
95             throw new NullPointerException JavaDoc(
96                     "Cannot end with a null trigger sequence"); //$NON-NLS-1$
97 }
98
99         return Util.endsWith(triggers, triggerSequence.triggers, equals);
100     }
101
102     public final boolean equals(final Object JavaDoc object) {
103         // Check if they're the same.
104 if (object == this) {
105             return true;
106         }
107
108         // Check if they're the same type.
109 if (!(object instanceof TriggerSequence)) {
110             return false;
111         }
112
113         final TriggerSequence triggerSequence = (TriggerSequence) object;
114         return Util.equals(triggers, triggerSequence.triggers);
115     }
116
117     /**
118      * Formats this trigger sequence into the current default look.
119      *
120      * @return A string representation for this trigger sequence using the
121      * default look; never <code>null</code>.
122      */
123     public abstract String JavaDoc format();
124
125     /**
126      * <p>
127      * Returns a list of prefixes for the current sequence. A prefix is any
128      * leading subsequence in a <code>TriggerSequence</code>. A prefix is
129      * also an instance of <code>TriggerSequence</code>.
130      * </p>
131      * <p>
132      * For example, consider a trigger sequence that consists of four triggers:
133      * A, B, C and D. The prefixes would be "", "A", "A B", and "A B C". The
134      * list of prefixes must always be the same as the size of the trigger list.
135      * </p>
136      *
137      * @return The array of possible prefixes for this sequence. This array must
138      * not be <code>null</code>, but may be empty. It must only
139      * contains instances of <code>TriggerSequence</code>.
140      */
141     public abstract TriggerSequence[] getPrefixes();
142
143     /**
144      * Returns the list of triggers.
145      *
146      * @return The triggers; never <code>null</code> and guaranteed to only
147      * contain instances of <code>Trigger</code>.
148      */
149     public final Trigger[] getTriggers() {
150         final int triggerLength = triggers.length;
151         final Trigger[] triggerCopy = new Trigger[triggerLength];
152         System.arraycopy(triggers, 0, triggerCopy, 0, triggerLength);
153         return triggerCopy;
154     }
155
156     /*
157      * (non-Javadoc)
158      *
159      * @see java.lang.Object#hashCode()
160      */
161     public final int hashCode() {
162         if (hashCode == HASH_CODE_NOT_COMPUTED) {
163             hashCode = HASH_INITIAL;
164             hashCode = hashCode * HASH_FACTOR + Util.hashCode(triggers);
165             if (hashCode == HASH_CODE_NOT_COMPUTED) {
166                 hashCode++;
167             }
168         }
169
170         return hashCode;
171     }
172
173     /**
174      * Returns whether or not this trigger sequence is empty.
175      *
176      * @return <code>true</code>, iff the trigger sequence is empty.
177      */
178     public final boolean isEmpty() {
179         return (triggers.length == 0);
180     }
181
182     /**
183      * Returns whether or not this trigger sequence starts with the given
184      * trigger sequence.
185      *
186      * @param triggerSequence
187      * a trigger sequence. Must not be <code>null</code>.
188      * @param equals
189      * whether or not an identical trigger sequence should be
190      * considered as a possible match.
191      * @return <code>true</code>, iff the given trigger sequence starts with
192      * this key sequence.
193      */
194     public final boolean startsWith(final TriggerSequence triggerSequence,
195             final boolean equals) {
196         if (triggerSequence == null) {
197             throw new NullPointerException JavaDoc(
198                     "A trigger sequence cannot start with null"); //$NON-NLS-1$
199 }
200
201         return Util.startsWith(triggers, triggerSequence.triggers, equals);
202     }
203 }
204
Popular Tags