Source code: net/jxta/platform/ModuleSpecID.java
1 /*
2 * Copyright (c) 2001 Sun Microsystems, Inc. All rights
3 * reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * 1. Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * 2. Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in
14 * the documentation and/or other materials provided with the
15 * distribution.
16 *
17 * 3. The end-user documentation included with the redistribution,
18 * if any, must include the following acknowledgment:
19 * "This product includes software developed by the
20 * Sun Microsystems, Inc. for Project JXTA."
21 * Alternately, this acknowledgment may appear in the software itself,
22 * if and wherever such third-party acknowledgments normally appear.
23 *
24 * 4. The names "Sun", "Sun Microsystems, Inc.", "JXTA" and "Project JXTA" must
25 * not be used to endorse or promote products derived from this
26 * software without prior written permission. For written
27 * permission, please contact Project JXTA at http://www.jxta.org.
28 *
29 * 5. Products derived from this software may not be called "JXTA",
30 * nor may "JXTA" appear in their name, without prior written
31 * permission of Sun.
32 *
33 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
34 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
35 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
36 * DISCLAIMED. IN NO EVENT SHALL SUN MICROSYSTEMS OR
37 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
38 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
39 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
40 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
41 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
42 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
43 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
44 * SUCH DAMAGE.
45 * ====================================================================
46 *
47 * This software consists of voluntary contributions made by many
48 * individuals on behalf of Project JXTA. For more
49 * information on Project JXTA, please see
50 * <http://www.jxta.org/>.
51 *
52 * This license is based on the BSD license adopted by the Apache Foundation.
53 *
54 * $Id: ModuleSpecID.java,v 1.4 2002/10/02 19:07:50 hamada Exp $
55 */
56
57 package net.jxta.platform;
58
59 import net.jxta.id.ID;
60
61 /**
62 * A ModuleSpecID uniquely identifies a particular network behaviour
63 * (wire protocol and choregraphy) that may be embodied by a Jxta Module.
64 * There may be any number of implementations of a given SpecID. All
65 * such implementations are assumed to be network compatible.
66 *
67 * <p>
68 * The Specification that corresponds to a given ModuleSpecID may be published
69 * in a ModuleSpecAdvertisement. This advertisement is uniquely identified by
70 * the ModuleSpecID that it describes.
71 *
72 * <p>
73 * The various implementations of a given SpecID may be published in
74 * ModuleImplAdvertisements. These advertisements are identified by the
75 * ModuleSpecID that they implement and a compatibility statement.
76 * ModuleImplAdvertisements baring the same SpecID and compatibility statement
77 * are theorethicaly interchangeable. However they may be subsequently discriminated
78 * by a Description element.
79 *
80 * <p>
81 * A ModuleSpecID embeds a ModuleClassID which uniquely identifies a base Module
82 * class. A base module class defines a local behaviour and one API per compatible
83 * JXTA implementation.
84 *
85 * <p>
86 * A ModuleSpecID therefore uniquely identifies an abstract module, of which an
87 * implementation compatible with the local JXTA implementation may be located and
88 * instantiated.
89 *
90 * <p>
91 * In the standard PeerGroup implementation of the java reference implementation
92 * the various services are specified as a list of ModuleSpecID, for each of which
93 * the group locates and loads an implementation as part of the group's
94 * initialization.
95 *
96 * @see net.jxta.peergroup.PeerGroup
97 * @see net.jxta.platform.Module
98 * @see net.jxta.platform.ModuleClassID
99 * @see net.jxta.protocol.ModuleSpecAdvertisement
100 * @see net.jxta.protocol.ModuleImplAdvertisement
101 * @see net.jxta.id.ID
102 * @see net.jxta.document.Advertisement
103 *
104 */
105
106 public abstract class ModuleSpecID extends ID {
107
108 /**
109 * Returns true if this ModuleSpecID is of the same base class than the
110 * given class.
111 * Note: This method is NOT named "isOfClass" because a ModuleClassID
112 * may have two portions; one that denotes a class proper,
113 * and an optional second one that denotes a "Role". For convenience, we refer
114 * the class stripped of its role portion as "the base class" although this is not
115 * a totally accurate term.
116 * A ModuleSpecID, is of a base class but is not related to any kind
117 * of role. So using "isOfClass" could be misleading.
118 * Base classes are represented by a class with the role ID set to zero, which
119 * happens to be a valid class. This routine may be used for comparison with
120 * such a class, of course.
121 *
122 * @param id Module class id to compare with
123 * @return boolean true if equals
124 *
125 */
126
127 public abstract boolean isOfSameBaseClass( ModuleClassID id );
128
129 /**
130 * Returns true if this ModuleSpecID is of the same base class than the
131 * the given ModuleSpecID.
132 *
133 * @param id Module spec id to compare with
134 * @return boolean true if equals
135 *
136 */
137
138 public abstract boolean isOfSameBaseClass( ModuleSpecID id );
139
140 /**
141 * Return a ModuleClassID of the same base class but with the role portion
142 * set to zero. aka "the base class".
143 *
144 * @return ModuleClassID the base class.
145 *
146 */
147
148 public abstract ModuleClassID getBaseClass( );
149 }