2 * Copyright (c) 2004-2007 Sun Microsystems, Inc. All rights reserved.
4 * The Sun Project JXTA(TM) Software License
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions are met:
9 * 1. Redistributions of source code must retain the above copyright notice,
10 * this list of conditions and the following disclaimer.
12 * 2. Redistributions in binary form must reproduce the above copyright notice,
13 * this list of conditions and the following disclaimer in the documentation
14 * and/or other materials provided with the distribution.
16 * 3. The end-user documentation included with the redistribution, if any, must
17 * include the following acknowledgment: "This product includes software
18 * developed by Sun Microsystems, Inc. for JXTA(TM) technology."
19 * Alternately, this acknowledgment may appear in the software itself, if
20 * and wherever such third-party acknowledgments normally appear.
22 * 4. The names "Sun", "Sun Microsystems, Inc.", "JXTA" and "Project JXTA" must
23 * not be used to endorse or promote products derived from this software
24 * without prior written permission. For written permission, please contact
25 * Project JXTA at http://www.jxta.org.
27 * 5. Products derived from this software may not be called "JXTA", nor may
28 * "JXTA" appear in their name, without prior written permission of Sun.
30 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
31 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
32 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SUN
33 * MICROSYSTEMS OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
34 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
35 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
36 * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
37 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
38 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
39 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
41 * JXTA is a registered trademark of Sun Microsystems, Inc. in the United
42 * States and other countries.
44 * Please see the license information page at :
45 * <http://www.jxta.org/project/www/license.html> for instructions on use of
46 * the license in source files.
48 * ====================================================================
50 * This software consists of voluntary contributions made by many individuals
51 * on behalf of Project JXTA. For more information on Project JXTA, please see
52 * http://www.jxta.org.
54 * This license is based on the BSD license adopted by the Apache Foundation.
56 package net.jxta.util;
59 * This the interface that all selectable objects expose.
62 * Applications programmers should treat this API as temporary, for now.
65 * A SimpleSelectable object can register SimpleSelector objects so that
66 * they are notified whenever this object chooses to report a change.
69 * SimpleSelectors are SimpleSelectable, therefore selectors can be selected.
72 * The change notification interface used to notify a selector is actually
73 * specified in SimpleSelectable. As a result, certain implementations may also
74 * allow to register SimpleSelectables that are not Selectors. Selectors themselves do not allow that.
77 * @see AbstractSimpleSelectable
79 public interface SimpleSelectable {
82 * A simple reference object that can be put in a map instead of the one it refers to.
83 * SimpleSelectable object often need to be put in maps where distinct objects are to be treated
84 * as such, even if they are identical at a semantical level. However, some
85 * SimpleSelectable objects may have semantically equals() and hashCode()
86 * methods rather than the identity ones.
89 * For that reason, whenever a SimpleSelectable needs to be used as a map or set key, its identity
90 * reference should be used instead. All SimpleSelectable can return an identity reference. A given
91 * SimpleSelectable always provides the same IdentityReference object. IdentityReference never overloads
92 * hashCode() and equals() in a way that could make different objects be equal or that could provide
93 * different results from invocation to invocation.
95 public static class IdentityReference {
96 private final SimpleSelectable object;
99 * Creates a new IdentityReference object
101 * @param object the selectable
103 public IdentityReference(SimpleSelectable object) {
104 this.object = object;
108 * @return The object that this one refers to.
110 public SimpleSelectable getObject() {
116 * @return A canonical IdentityReference for this object.
117 * A given SimpleSelectable always provides the same IdentityReference
118 * object. An IdentityReference must never overload hashCode() or equals()
119 * in a way that could make different objects be equal or that could provide
120 * different results from invocation to invocation.
122 public IdentityReference getIdentityReference();
125 * Registers the given selector with this selectable object. This always
126 * causes one change event for this object to be reported through the
127 * selector. As a result, when selecting for a condition, it is not
128 * necessary to verify whether it has already happened or not; the next call
129 * to select will be able to detect it.
131 * @param s The SimpleSelector to register
133 public void register(SimpleSelector s);
136 * Unregisters the given selector, so that it is no-longer notified when
137 * this object changes.
139 * @param s The SimpleSelector to unregister
141 public void unregister(SimpleSelector s);
144 * This method is invoked when the given selectable object has changed. This
145 * permits to cascade selectable objects, so that one reports a change when
146 * the other changes, without having to select it. This also permits
147 * implementation of this interface by delegating its implementation to a
150 * An implementation may do what it wants about it. For example, a
151 * {@link SimpleSelector} will report the change to
152 * {@link SimpleSelector#select} and invoke
153 * {@link AbstractSimpleSelectable#notifyChange()} thereby reporting its own
154 * change to cascaded selectors. Other implementations may only invoke
155 * {@link AbstractSimpleSelectable#notifyChange()} or may perform more
158 * @see AbstractSimpleSelectable
160 * @param changedObject the object that has changed.
162 public void itemChanged(SimpleSelectable changedObject);