Source code: net/jxta/impl/id/binaryID/ModuleClassBinaryID.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: ModuleClassBinaryID.java,v 1.5 2003/06/04 17:15:20 bondolo Exp $
55 */
56
57 package net.jxta.impl.id.binaryID;
58
59 import java.net.URL;
60
61 import org.apache.log4j.Logger;
62 import org.apache.log4j.Level;
63 import net.jxta.peergroup.PeerGroupID;
64 /**
65 * This interface defines a Module Class Identifier.
66 * A ModuleClassID uniquely identifies a particular local behaviour, that is,
67 * a specific API for each execution environment for which an implementation
68 * exists.
69 *
70 * <p>
71 * A ModuleClassID has two components: A base class identifier, and a role identifier.
72 * The role identifier may be zero. By convention the API uses the ModuleClassID with
73 * a zero role identifier to designate the base class in contexts where only the base class
74 * is significant. Nonetheless, a ModuleClassID with a zero role identifier is a valid
75 * ModulesClassID wherever a full ModuleClassID is expected. In many cases, only one role
76 * in a given class is ever used. Using role zero in such cases is an optimization because
77 * it may make the string representation of the ModuleClassID shorter.
78 *
79 * <p>
80 * Each service of a group, that is, the role it plays in the group, is uniquely identified
81 * per the group definition.
82 * This identifier may be used by other modules in the group to designate this one, or by the service
83 * itself to identify its parameters in a PeerAdvertisement. In addition, by combining its
84 * PeerGroupID with its own ModuleClassID, a service may create a predictible identifier unique
85 * on their peer, suitable for registering listeners with the EndpointService or other services
86 * with similar listener interfaces.
87 *
88 * <p>
89 * The standard PeerGroup implementation of the java reference implementation
90 * assigns to each service its ModuleClassID as its unique service identifier. Most of the
91 * times this ModuleClassID is a base classID, but groups that use the same Module Class
92 * for more than one service (same behaviour but playing a different role in the group, such
93 * as, for example, a data base engine with a different data base), may define multiple roles
94 * identified by the same base class identifier but different role identifiers. The standard
95 * PeerGroup implementation of the java reference implementation has the notion of main
96 * application: a default application which may be started automatically upon instantiating
97 * the group. This application implements Module and, therefore, is assigned a ModuleClassID.
98 * However applications are not expected to play any specific role in the group. As a result, they
99 * are assigned a role identifier allocated at run-time as need to garantee local unicity. As
100 * a result main applications cannot expect a predictible ClassID.
101 *
102 * <p>
103 * A ModuleClassID is optionaly described by a published ModuleClassAdvertisement.
104 *
105 * <p>
106 * There may be any number of embodiements of a module class. These are module
107 * specifications. A module specification represent the network behaviour of a
108 * module while its class represents its local behaviour. Different groups
109 * may use a common subset of classes, for example, the basic set defined by the platform
110 * should always be part of it. Each group may use different and network-incompatible
111 * specifications for common classes, optimized for various purposes. The local API of a
112 * given class on a given JXTA implementation will be invariant per the spec being used.
113 * Therefore, the difference will be transparent to applications which do not depend
114 * on the possibly different quality of service.
115 *
116 * <p>
117 * A ModuleSpecID embeds a base class identifier, which permits to verify that
118 * a given Module specification is suitable for its intended use.
119 *
120 * @author Daniel Brookshier <a HREF="mailto:turbogeek@cluck.com">turbogeek@cluck.com</a>
121 *
122 * @see net.jxta.peergroup.PeerGroup
123 * @see net.jxta.platform.Module
124 * @see net.jxta.platform.ModuleClassID
125 * @see net.jxta.protocol.PeerAdvertisement
126 * @see net.jxta.protocol.ModuleSpecAdvertisement
127 * @see net.jxta.protocol.ModuleClassAdvertisement
128 * @see net.jxta.endpoint.EndpointService
129 * @see net.jxta.id.ID
130 *
131 */
132
133 public final class ModuleClassBinaryID extends net.jxta.platform.ModuleClassID {
134
135 /**
136 * Log4J categorgy
137 **/
138 private static final org.apache.log4j.Logger LOG = org.apache.log4j.Logger.getLogger(ModuleClassBinaryID.class.getName());
139
140 /**
141 * The id data
142 **/
143 protected BinaryID classID;
144 protected BinaryID parentClassID;
145 protected BinaryID roleID;
146 protected PeerGroupID peerGroupID;
147 /**
148 * Constructor.
149 * Intializes contents from provided ID.
150 *
151 * @since JXTA 1.0
152 *
153 * @param id the ID data
154 **/
155 protected ModuleClassBinaryID(String id) {
156 super();
157 int start = id.indexOf('-');
158 int parent = id.indexOf(start+1,'-');
159 int role = id.indexOf(id.indexOf(parent+1,'-')+1,'-');
160 int group = id.indexOf(id.indexOf(role+1,'-')+1,'-');
161 classID = new BinaryID(id.substring(group+1,parent));
162 parentClassID = new BinaryID(id.substring(parent+1,role));
163 roleID = new BinaryID(id.substring(role+1,group));
164 peerGroupID = new PeerGroupBinaryID(new BinaryID(id.substring(group+1)));
165 }
166
167 /**
168 * Constructor.
169 * Creates a ModuleClassID in a given class, with a given class unique id.
170 * A BinaryID of a class and another BinaryID are provided.
171 *
172 * @since JXTA 1.0
173 *
174 * @param classBinaryID the class to which this will belong.
175 * @param roleBinaryID the unique id of this role in that class.
176 **/
177 protected ModuleClassBinaryID(BinaryID classID, BinaryID parentClassID, BinaryID roleID, PeerGroupID peerGroupID) {
178 super();
179 this.classID=classID;
180 this.parentClassID = parentClassID;
181 this.roleID = roleID;
182 this.peerGroupID = peerGroupID;
183 }
184 protected ModuleClassBinaryID(BinaryID classID, BinaryID parentClassID, BinaryID roleID, BinaryID peerGroupID) {
185 super();
186 this.classID=classID;
187 this.parentClassID = parentClassID;
188 this.roleID = roleID;
189 this.peerGroupID = new PeerGroupBinaryID(peerGroupID);
190 }
191
192 /**
193 * Constructor for creating a new ModuleClassID. A new class BinaryID is
194 * created. The role ID is left null. This is the only way to create
195 * a new class without supplying a new BinaryID explicitly.
196 * To create a new role in an existing class, one must use one of
197 * the other constructors.
198 * Note that a null role is just as valid as any other, it just has a
199 * shorter string representation. So it is not mandatory to create a new
200 * role in a new class.
201 *
202 * @since JXTA 1.0
203 **/
204 public ModuleClassBinaryID() {
205 this(new BinaryID(BinaryID.flagModuleClassID)
206 ,new BinaryID(BinaryID.flagModuleClassID)
207 ,new BinaryID(BinaryID.flagModuleClassRoleID)
208 ,new BinaryID(BinaryID.flagPeerGroupID) );
209 }
210
211 /**
212 * {@inheritDoc}
213 */
214 public boolean equals(Object target) {
215 ModuleClassBinaryID targetObj = (ModuleClassBinaryID)target;
216 if (this == target) {
217 return true;
218 }else if( this.classID.equals(targetObj.getClassID())&&
219 this.parentClassID.equals(targetObj.getBaseClass()) &&
220 this.roleID.equals(targetObj.getRoleID()) &&
221 this.peerGroupID.equals(targetObj.getPeerGroupID()) ){
222 return true;
223 } else {
224 return false;
225 }
226 }
227
228 /**
229 * {@inheritDoc}
230 */
231 public int hashCode() {
232 return getUniqueValue().hashCode();
233 }
234
235 /**
236 * {@inheritDoc}
237 */
238 public String getIDFormat() {
239 return IDFormat.INSTANTIATOR.getSupportedIDFormat();
240 }
241
242 /**
243 * {@inheritDoc}
244 */
245 public Object getUniqueValue() {
246 return getIDFormat()
247 +"-" +classID.getID()
248 +"-"+parentClassID.getID()
249 +"-"+roleID.getID()
250 +"-"+peerGroupID.getUniqueValue();
251 }
252
253 /**
254 * {@inheritDoc}
255 */
256 public URL getURL() {
257 return IDFormat.getURL((String) getUniqueValue());
258 }
259
260 /**
261 * {@inheritDoc}
262 */
263 public net.jxta.id.ID getPeerGroupID() {
264 return peerGroupID;
265 }
266
267 /**
268 * returns the coded ID without the binaryid tag.
269 *
270 * @return string of the contents
271 */
272 protected String getID() {
273 return classID.getID()
274 +"*"+parentClassID.getID()
275 +"*"+roleID.getID()
276 +"*"+peerGroupID.getUniqueValue();
277 }
278 /**
279 * {@inheritDoc}
280 **/
281 public net.jxta.platform.ModuleClassID getBaseClass( ) {
282 return new ModuleClassBinaryID(parentClassID, new BinaryID(), new BinaryID(), new BinaryID());
283 }
284
285 /**
286 * {@inheritDoc}
287 **/
288 public boolean isOfSameBaseClass( net.jxta.platform.ModuleClassID classId ) {
289 return getClass().equals( ((ModuleClassBinaryID) classId).getClass( ) );
290 }
291
292 /**
293 * {@inheritDoc}
294 **/
295 public boolean isOfSameBaseClass( net.jxta.platform.ModuleSpecID specId ) {
296 return getBaseClassID().equals(((ModuleSpecBinaryID)specId).getBaseClassID( ) );
297 }
298
299 /**
300 * get the class' unique id
301 *
302 * @since JXTA 1.0
303 *
304 * @return BinaryID module class' unique id
305 **/
306 public BinaryID getClassID( ) {
307 return classID;
308 }
309
310 /**
311 * get the role unique id
312 *
313 * @since JXTA 1.0
314 *
315 * @return Module role unique id.
316 **/
317 public BinaryID getRoleID( ) {
318 return roleID;
319 }
320
321
322 /** Getter for property parentClassID.
323 * @return Value of property parentClassID.
324 *
325 */
326 public BinaryID getBaseClassID() {
327 return parentClassID;
328 }
329
330
331 }