Source code: net/jxta/protocol/ModuleSpecAdvertisement.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: ModuleSpecAdvertisement.java,v 1.16 2004/05/07 00:03:14 hamada Exp $
55 */
56
57 package net.jxta.protocol;
58
59 import net.jxta.document.ExtendableAdvertisement;
60 import net.jxta.document.StructuredDocument;
61 import net.jxta.document.Element;
62 import net.jxta.document.StructuredDocumentUtils;
63 import net.jxta.id.ID;
64 import net.jxta.platform.ModuleSpecID;
65
66 /**
67 * A ModuleSpecAdvertisement describes a module specification.
68 * Its main purpose is to provide references to the documentation
69 * needed in order to create conforming implementations of that
70 * specification. A secondary use is, optionally, to make running instances
71 * usable remotely, by publishing any or all of the following:<br>
72 * <ul>
73 * <li> PipeAdvertisement
74 * <li> ModuleSpecID of a proxy module
75 * <li> ModuleSpecID of an authenticator module
76 * </ul>
77 * Not all modules are usable remotely, it is up to the specification creator
78 * to make that choice. However, if the specification dictates it, all
79 * implementations can be expected to support it.
80 * <p>
81 * Note that the Standard PeerGroup implementation of the java reference
82 * implementation does <em>not</em> support replacing a group service with
83 * a pipe to a remote instance. However, nothing prevents a particular
84 * implementation of a group from using a proxy module in place of the fully
85 * version; provided that the API (and therefore the ClassIDs) of the proxy
86 * and local versions are identical.
87 * <p>
88 * Note also that in the case of the local+proxy style, it is up to the
89 * implementation of both sides to figure-out which pipe to listen to or
90 * connect to. The safest method is probably for the full version to seek its
91 * own ModuleSpecAdvertisement, and for the proxy version to accept the
92 * full version's ModuleSpecAdvertisement as a parameter.
93 * Alternatively if the proxy version is completely dedicated to the
94 * specification that it proxies, both sides may have the PipeID and type
95 * hard-coded.
96 *
97 * @see net.jxta.platform.ModuleSpecID
98 * @see net.jxta.protocol.PipeAdvertisement
99 * @see net.jxta.protocol.ModuleImplAdvertisement
100 * @see net.jxta.document.Advertisement
101 */
102 public abstract class ModuleSpecAdvertisement extends ExtendableAdvertisement
103 implements Cloneable {
104
105 private String name = null;
106 private ModuleSpecID id = null;
107 private String creator = null;
108 private String uri = null;
109 private String version = null;
110 private String description = null;
111 private PipeAdvertisement pipeAdv = null;
112 private ModuleSpecID proxySpecID = null;
113 private ModuleSpecID authSpecID = null;
114
115 // The module interprets this. It is not necessarily final and immutable
116 // so it may need cloning for making a fully correct clone adv.
117 private StructuredDocument param = null;
118
119 /**
120 * Returns the identifying type of this Advertisement.
121 *
122 * @return String the type of advertisement
123 **/
124 public static String getAdvertisementType() {
125 return "jxta:MSA" ;
126 }
127
128 /**
129 * {@inheritDoc}
130 **/
131 public final String getBaseAdvType() {
132 return getAdvertisementType();
133 }
134
135 /**
136 * Clone this ModuleSpecAdvertisement
137 *
138 * @return Object an object of class ModuleSpecAdvertisement that is a
139 * deep-enough copy of this one.
140 */
141 public Object clone() {
142
143 // All members are either immutable or never modified nor allowed to
144 // be modified: all accessors return clones. IDs are know to be
145 // immutable but that could change. clone() them for safety; their
146 // clone method costs nothing.
147 try {
148 return super.clone();
149 } catch (CloneNotSupportedException impossible) {
150 return null;
151 }
152 }
153
154 /**
155 * returns the id of the spec
156 * @return ModuleSpecID the spec id
157 *
158 */
159
160 public ModuleSpecID getModuleSpecID() {
161 return id;
162 }
163
164 /**
165 * sets the id of the spec
166 * @param id The id of the spec
167 *
168 */
169
170 public void setModuleSpecID(ModuleSpecID id) {
171 this.id = id;
172 }
173
174 /**
175 * returns a unique id for that adv for the purpose of indexing.
176 * The spec id uniquely identifies this advertisement.
177 *
178 * @return ID the spec id as a basic ID.
179 *
180 */
181
182 public ID getID() {
183 return id;
184 }
185
186 /**
187 * returns the name of the module spec
188 * @return String name of the module spec
189 *
190 */
191
192 public String getName() {
193 return name;
194 }
195
196 /**
197 * sets the name of the module spec
198 * @param name name of the module spec to be set
199 *
200 */
201
202 public void setName(String name) {
203 this.name = name;
204 }
205
206 /**
207 * Returns the creator of the module spec, in case someone cares.
208 *
209 * @return String the creator.
210 *
211 */
212
213 public String getCreator() {
214 return creator;
215 }
216
217 /**
218 * Sets the creator of this module spec.
219 * Note: the usefulness of this is unclear.
220 *
221 * @param creator name of the creator of the module
222 *
223 */
224
225 public void setCreator(String creator) {
226 this.creator = creator;
227 }
228
229 /**
230 * returns the uri. This uri normally points at the actual specification
231 * that this advertises.
232 * @return String uri
233 *
234 */
235
236 public String getSpecURI() {
237 return uri;
238 }
239
240 /**
241 * sets the uri
242 * @param uri string uri
243 *
244 */
245
246 public void setSpecURI(String uri) {
247 this.uri = uri;
248 }
249
250 /**
251 * returns the specification version number
252 * @return String version number
253 *
254 */
255
256 public String getVersion() {
257 return version;
258 }
259
260 /**
261 * sets the version of the module
262 * @param version version number
263 *
264 */
265
266 public void setVersion(String version) {
267 this.version = version;
268 }
269
270 /**
271 * returns the keywords/description associated with this class
272 * @return String keywords/description associated with the class
273 *
274 */
275
276 public String getDescription() {
277 return description;
278 }
279
280 /**
281 * sets the description associated with this class
282 * @param description
283 *
284 */
285
286 public void setDescription(String description) {
287 this.description = description;
288 }
289
290 /**
291 * returns the param element.
292 *
293 * @return Element parameters as an Element of unspecified content.
294 *
295 */
296
297 public StructuredDocument getParam() {
298 return (param == null ? null : StructuredDocumentUtils.copyAsDocument(param));
299 }
300
301 /**
302 * Privileged version of {@link #getParam()} that does not clone the elements.
303 *
304 * @return StructuredDocument A stand-alone structured document of
305 * unspecified content.
306 **/
307 protected StructuredDocument getParamPriv() {
308 return param;
309 }
310
311 /**
312 * sets the param element.
313 * @param param Element of an unspecified content.
314 *
315 */
316
317 public void setParam(Element param) {
318 this.param = (param == null ? null : StructuredDocumentUtils.copyAsDocument(param));
319 }
320
321 /**
322 * returns the embedded pipe advertisement if any.
323 *
324 * @return PipeAdvertisement the Pipe Advertisement. null if none exists.
325 *
326 */
327
328 public PipeAdvertisement getPipeAdvertisement() {
329 return (pipeAdv == null ? null : (PipeAdvertisement) pipeAdv.clone());
330 }
331
332 /**
333 * sets an embedded pipe advertisement.
334 *
335 * @param pipeAdv the Pipe Advertisement. null is authorized.
336 *
337 */
338
339 public void setPipeAdvertisement(PipeAdvertisement pipeAdv) {
340 this.pipeAdv = (pipeAdv == null ? null : (PipeAdvertisement) pipeAdv.clone());
341 }
342
343 /**
344 * returns the specID of a proxy module.
345 * @return ModuleSpecID the spec id
346 *
347 */
348
349 public ModuleSpecID getProxySpecID() {
350 return proxySpecID;
351 }
352
353 /**
354 * sets a proxy module specID
355 * @param proxySpecID The spec id
356 *
357 */
358
359 public void setProxySpecID(ModuleSpecID proxySpecID) {
360 this.proxySpecID = proxySpecID;
361 }
362
363 /**
364 * returns the specID of an authenticator module.
365 * @return ModuleSpecID the spec id
366 *
367 */
368
369 public ModuleSpecID getAuthSpecID() {
370 return authSpecID;
371 }
372
373 /**
374 * sets an authenticator module specID
375 * @param authSpecID The spec id
376 *
377 */
378
379 public void setAuthSpecID(ModuleSpecID authSpecID) {
380 this.authSpecID = authSpecID;
381 }
382 }