Source code: net/jxta/platform/ModuleClassID.java
1 /*
2 * Copyright (c) 2001 Sun Microsystems, Inc. All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
6 * are met:
7 *
8 * 1. Redistributions of source code must retain the above copyright
9 * notice, this list of conditions and the following disclaimer.
10 *
11 * 2. Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in
13 * the documentation and/or other materials provided with the
14 * distribution.
15 *
16 * 3. The end-user documentation included with the redistribution,
17 * if any, must include the following acknowledgment:
18 * "This product includes software developed by the
19 * Sun Microsystems, Inc. for Project JXTA."
20 * Alternately, this acknowledgment may appear in the software itself,
21 * if and wherever such third-party acknowledgments normally appear.
22 *
23 * 4. The names "Sun", "Sun Microsystems, Inc.", "JXTA" and "Project JXTA" must
24 * not be used to endorse or promote products derived from this
25 * software without prior written permission. For written
26 * permission, please contact Project JXTA at http://www.jxta.org.
27 *
28 * 5. Products derived from this software may not be called "JXTA",
29 * nor may "JXTA" appear in their name, without prior written
30 * permission of Sun.
31 *
32 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
33 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
34 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
35 * DISCLAIMED. IN NO EVENT SHALL SUN MICROSYSTEMS OR
36 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
37 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
38 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
39 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
40 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
41 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
42 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
43 * SUCH DAMAGE.
44 * ====================================================================
45 *
46 * This software consists of voluntary contributions made by many
47 * individuals on behalf of Project JXTA. For more
48 * information on Project JXTA, please see
49 * <http://www.jxta.org/>.
50 *
51 * This license is based on the BSD license adopted by the Apache Foundation.
52 *
53 * $Id: ModuleClassID.java,v 1.4 2003/03/21 00:21:05 bondolo Exp $
54 */
55
56 package net.jxta.platform;
57
58 import net.jxta.id.ID;
59
60 /**
61 * A ModuleClassID uniquely identifies a particular local behaviour, that is,
62 * a specific API for each execution environment for which an implementation
63 * exists.
64 *
65 * <p/>A ModuleClassID has two components: A base class identifier, and a role identifier.
66 * The role identifier may be zero. By convention the API uses the ModuleClassID with
67 * a zero role identifier to designate the base class in contexts where only the base class
68 * is significant. Nonetheless, a ModuleClassID with a zero role identifier is a valid
69 * ModulesClassID wherever a full ModuleClassID is expected. In many cases, only one role
70 * in a given class is ever used. Using role zero in such cases is an optimization because
71 * it may make the string representation of the ModuleClassID shorter.
72 *
73 * <p/>Each service of a group, that is, the role it plays in the group, is uniquely identified
74 * per the group definition.
75 * This identifier may be used by other modules in the group to designate this one, or by the service
76 * itself to identify its parameters in a PeerAdvertisement. In addition, by combining its
77 * PeerGroupID with its own ModuleClassID, a service may create a predictible identifier unique
78 * on their peer, suitable for registering listeners with the EndpointService or other services
79 * with similar listener interfaces.
80 *
81 * <p/>The standard PeerGroup implementation of the java reference implementation
82 * assigns to each service its ModuleClassID as its unique service identifier. Most of the
83 * times this ModuleClassID is a base classID, but groups that use the same Module Class
84 * for more than one service (same behaviour but playing a different role in the group, such
85 * as, for example, a data base engine with a different data base), may define multiple roles
86 * identified by the same base class identifier but different role identifiers. The standard
87 * PeerGroup implementation of the java reference implementation has the notion of main
88 * application: a default application which may be started automatically upon instantiating
89 * the group. This application implements Module and, therefore, is assigned a ModuleClassID.
90 * However applications are not expected to play any specific role in the group. As a result, they
91 * are assigned a role identifier allocated at run-time as need to garantee local unicity. As
92 * a result main applications cannot expect a predictible ClassID.
93 *
94 * <p/>A ModuleClassID is optionaly described by a published ModuleClassAdvertisement.
95 *
96 * <p/>There may be any number of embodiements of a module class. These are module
97 * specifications. A module specification represent the network behaviour of a
98 * module while its class represents its local behaviour. Different groups
99 * may use a common subset of classes, for example, the basic set defined by the platform
100 * should always be part of it. Each group may use different and network-incompatible
101 * specifications for common classes, optimized for various purposes. The local API of a
102 * given class on a given JXTA implementation will be invariant per the spec being used.
103 * Therefore, the difference will be transparent to applications which do not depend
104 * on the possibly different quality of service.
105 *
106 * <p/>A ModuleSpecID embeds a base class identifier, which permits to verify that
107 * a given Module specification is suitable for its intended use.
108 *
109 * @see net.jxta.peergroup.PeerGroup
110 * @see net.jxta.platform.Module
111 * @see net.jxta.platform.ModuleClassID
112 * @see net.jxta.protocol.PeerAdvertisement
113 * @see net.jxta.protocol.ModuleSpecAdvertisement
114 * @see net.jxta.protocol.ModuleClassAdvertisement
115 * @see net.jxta.endpoint.EndpointService
116 * @see net.jxta.id.ID
117 *
118 */
119 public abstract class ModuleClassID extends ID {
120
121 /**
122 * Returns true if this ModuleClassID is of the same base class than the
123 * given class.
124 * Note: This method is NOT named "isOfClass" because a ModuleClassID
125 * may have two UUID; one that denotes a "base" class proper,
126 * and an optional second one that denotes a "Role", or subclass.
127 * Compatibility between ClassIDs is based on the "base" portion, hence the
128 * "isOfSame" naming. This routine can be used for comparison with a base class
129 * since a base class is just a class which role portion happens to be zero.
130 *
131 * @param id Module class id to compare with
132 * @return boolean true if equals
133 **/
134
135 public abstract boolean isOfSameBaseClass ( ModuleClassID id );
136
137 /**
138 * Returns true if this ModuleClassID is of the same class than the
139 * the given ModuleSpecID.
140 *
141 * @param id Module spec id to compare with
142 * @return boolean true if equals
143 **/
144
145 public abstract boolean isOfSameBaseClass ( ModuleSpecID id );
146
147 /**
148 * Return a ModuleClassID of the same base class but with the role portion
149 * set to zero. aka "the base class".
150 *
151 * @return ModuleClassID the base class.
152 **/
153 public abstract ModuleClassID getBaseClass ( );
154 }