1 /*
2 * Copyright (c) 2008, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package com.sun.servicetag;
27
28 import java.util.Date;
29 import java.io.IOException;
30 import static com.sun.servicetag.RegistrationDocument.*;
31
32 /**
33 * A service tag is an XML-based data structure that identifies a product or
34 * a component on a system. The service tag schema is defined by the
35 * Service Tags Technology. The location of the DTD file is platform dependent.
36 * On Solaris, see <tt>/usr/share/lib/xml/dtd/servicetag.dtd</tt>.
37 * <p>
38 * A valid {@code ServiceTag} instance must comply to the service tag schema
39 * and contain the following fields:
40 * <ul>
41 * <li>{@link #getInstanceURN <tt>instance_urn</tt>}</li>
42 * <li>{@link #getProductName <tt>product_name</tt>}</li>
43 * <li>{@link #getProductVersion <tt>product_version</tt>}</li>
44 * <li>{@link #getProductURN <tt>product_urn</tt>}</li>
45 * <li>{@link #getProductParent <tt>product_parent</tt>}</li>
46 * <li>{@link #getProductParentURN <tt>product_parent_urn</tt>}</li>
47 * <li>{@link #getProductDefinedInstanceID <tt>product_defined_inst_id</tt>}</li>
48 * <li>{@link #getProductVendor <tt>product_vendor</tt>}</li>
49 * <li>{@link #getPlatformArch <tt>platform_arch</tt>}</li>
50 * <li>{@link #getContainer <tt>container</tt>}</li>
51 * <li>{@link #getSource <tt>source</tt>}</li>
52 * <li>{@link #getInstallerUID <tt>installer_uid</tt>}</li>
53 * <li>{@link #getTimestamp <tt>timestamp</tt>}</li>
54 * </ul>
55 *
56 * The <tt>instance_urn</tt> can be specified when a {@code ServiceTag}
57 * object is created, or it can be generated when it is added to
58 * a {@link RegistrationData} object, or {@link Registry
59 * system service tag registry}. The <tt>installer_uid</tt> and
60 * <tt>timestamp</tt> are set when a {@code ServiceTag} object
61 * is added to a {@link RegistrationData} object, or {@link Registry
62 * system service tag registry}.
63 *
64 * @see <a href="https://sunconnection.sun.com/FAQ/sc_faq.html">Service Tags FAQ</a>
65 */
66 public class ServiceTag {
67
68 private String instanceURN;
69 private String productName;
70 private String productVersion;
71 private String productURN;
72 private String productParent;
73 private String productParentURN;
74 private String productDefinedInstanceID;
75 private String productVendor;
76 private String platformArch;
77 private String container;
78 private String source;
79 private int installerUID;
80 private Date timestamp;
81
82 // Service Tag Field Lengths (defined in sthelper.h)
83 // Since the constants defined in sthelper.h includes the null-terminated
84 // character, so minus 1 from the sthelper.h defined values.
85 private final int MAX_URN_LEN = 256 - 1;
86 private final int MAX_PRODUCT_NAME_LEN = 256 - 1;
87 private final int MAX_PRODUCT_VERSION_LEN = 64 - 1;
88 private final int MAX_PRODUCT_PARENT_LEN = 256 - 1;
89 private final int MAX_PRODUCT_VENDOR_LEN = 64 - 1;
90 private final int MAX_PLATFORM_ARCH_LEN = 64 - 1;
91 private final int MAX_CONTAINER_LEN = 64 - 1;
92 private final int MAX_SOURCE_LEN = 64 - 1;
93
94 // private constructors
95 private ServiceTag() {
96 }
97 // package private
98 ServiceTag(String instanceURN,
99 String productName,
100 String productVersion,
101 String productURN,
102 String productParent,
103 String productParentURN,
104 String productDefinedInstanceID,
105 String productVendor,
106 String platformArch,
107 String container,
108 String source,
109 int installerUID,
110 Date timestamp) {
111 setInstanceURN(instanceURN);
112 setProductName(productName);
113 setProductVersion(productVersion);
114 setProductURN(productURN);
115 setProductParentURN(productParentURN);
116 setProductParent(productParent);
117 setProductDefinedInstanceID(productDefinedInstanceID);
118 setProductVendor(productVendor);
119 setPlatformArch(platformArch);
120 setContainer(container);
121 setSource(source);
122 setInstallerUID(installerUID);
123 setTimestamp(timestamp);
124 }
125
126 /**
127 * Creates a service tag object with no <tt>instance_urn</tt>.
128 *
129 * @param productName the name of the product.
130 * @param productVersion the version of the product.
131 * @param productURN the uniform resource name of the product
132 * @param productParent the name of the product's parent.
133 * @param productParentURN the uniform resource name of the product's parent.
134 * @param productDefinedInstanceID the instance identifier.
135 * @param productVendor the vendor of the product.
136 * @param platformArch the operating system architecture.
137 * @param container the container of the product.
138 * @param source the source of the product.
139 *
140 * @throws IllegalArgumentException if any value of the input fields
141 * does not conform to the service tag XML schema.
142 */
143 public static ServiceTag newInstance(String productName,
144 String productVersion,
145 String productURN,
146 String productParent,
147 String productParentURN,
148 String productDefinedInstanceID,
149 String productVendor,
150 String platformArch,
151 String container,
152 String source) {
153 return new ServiceTag("", /* empty instance_urn */
154 productName,
155 productVersion,
156 productURN,
157 productParent,
158 productParentURN,
159 productDefinedInstanceID,
160 productVendor,
161 platformArch,
162 container,
163 source,
164 -1,
165 null);
166 }
167
168 /**
169 * Creates a service tag object with a specified <tt>instance_urn</tt>.
170 *
171 * @param instanceURN the uniform resource name of this instance.
172 * @param productName the name of the product.
173 * @param productVersion the version of the product.
174 * @param productURN the uniform resource name of the product
175 * @param productParent the name of the product's parent.
176 * @param productParentURN the uniform resource name of the product's parent.
177 * @param productDefinedInstanceID the instance identifier.
178 * @param productVendor the vendor of the product.
179 * @param platformArch the operating system architecture.
180 * @param container the container of the product.
181 * @param source the source of the product.
182 *
183 * @throws IllegalArgumentException if any value of the input fields
184 * does not conform to the service tag XML schema.
185 */
186 public static ServiceTag newInstance(String instanceURN,
187 String productName,
188 String productVersion,
189 String productURN,
190 String productParent,
191 String productParentURN,
192 String productDefinedInstanceID,
193 String productVendor,
194 String platformArch,
195 String container,
196 String source) {
197 return new ServiceTag(instanceURN,
198 productName,
199 productVersion,
200 productURN,
201 productParent,
202 productParentURN,
203 productDefinedInstanceID,
204 productVendor,
205 platformArch,
206 container,
207 source,
208 -1,
209 null);
210 }
211
212 // Creates a copy of the ServiceTag instance
213 // with instance_urn and timestamp initialized
214 static ServiceTag newInstanceWithUrnTimestamp(ServiceTag st) {
215 String instanceURN =
216 (st.getInstanceURN().length() == 0 ? Util.generateURN() :
217 st.getInstanceURN());
218 ServiceTag svcTag = new ServiceTag(instanceURN,
219 st.getProductName(),
220 st.getProductVersion(),
221 st.getProductURN(),
222 st.getProductParent(),
223 st.getProductParentURN(),
224 st.getProductDefinedInstanceID(),
225 st.getProductVendor(),
226 st.getPlatformArch(),
227 st.getContainer(),
228 st.getSource(),
229 st.getInstallerUID(),
230 new Date());
231 return svcTag;
232 }
233
234 /**
235 * Returns a uniform resource name (URN) in this format:
236 * <blockquote>
237 * "<tt>urn:st:<32-char {@link java.util.UUID uuid}></tt>"
238 * </blockquote>
239 * @return a URN.
240 */
241 public static String generateInstanceURN() {
242 return Util.generateURN();
243 }
244
245 /**
246 * Returns the uniform resource name of this service tag instance.
247 *
248 * @return the <tt>instance_urn</tt> of this service tag.
249 */
250 public String getInstanceURN() {
251 return instanceURN;
252 }
253
254 /**
255 * Returns the name of the product.
256 *
257 * @return the product name.
258 */
259 public String getProductName() {
260 return productName;
261 }
262
263 /**
264 * Returns the version of the product.
265 *
266 * @return the product version.
267 */
268 public String getProductVersion() {
269 return productVersion;
270 }
271
272 /**
273 * Returns the uniform resource name of the product.
274 *
275 * @return the product URN.
276 */
277 public String getProductURN() {
278 return productURN;
279 }
280
281 /**
282 * Returns the uniform resource name of the product's parent.
283 *
284 * @return the product's parent URN.
285 */
286 public String getProductParentURN() {
287 return productParentURN;
288 }
289
290 /**
291 * Returns the name of the product's parent.
292 *
293 * @return the product's parent name.
294 */
295 public String getProductParent() {
296 return productParent;
297 }
298
299 /**
300 * Returns the identifier defined for this product instance.
301 *
302 * @return the identifier defined for this product instance.
303 */
304 public String getProductDefinedInstanceID() {
305 return productDefinedInstanceID;
306 }
307
308 /**
309 * Returns the vendor of the product.
310 *
311 * @return the product vendor.
312 */
313 public String getProductVendor() {
314 return productVendor;
315 }
316
317 /**
318 * Returns the platform architecture on which the product
319 * is running on.
320 *
321 * @return the platform architecture on which the product is running on.
322 */
323 public String getPlatformArch() {
324 return platformArch;
325 }
326
327 /**
328 * Returns the timestamp. This timestamp is set when this service tag
329 * is added to or updated in a {@code RegistrationData} object or
330 * the system service tag registry.
331 * This method may return {@code null}.
332 *
333 * @return timestamp when this service tag
334 * is added to or updated in a {@code RegistrationData} object or
335 * the system service tag registry, or {@code null}.
336 */
337 public Date getTimestamp() {
338 if (timestamp != null) {
339 return (Date) timestamp.clone();
340 } else {
341 return null;
342 }
343 }
344
345
346 /**
347 * Returns the container of the product.
348 *
349 * @return the container of the product.
350 */
351 public String getContainer() {
352 return container;
353 }
354
355 /**
356 * Returns the source of this service tag.
357 *
358 * @return source of this service tag.
359 */
360 public String getSource() {
361 return source;
362 }
363
364 /**
365 * Returns the UID. The UID is set when this service tag
366 * is added to or updated in the system service tag registry.
367 * This is platform dependent whose default value is {@code -1}.
368 * When this service tag is added to a {@code RegistrationData},
369 * the UID is not set.
370 *
371 * @return the UID of whom this service tag
372 * is added to or updated in the system service tag registry,
373 * or {@code -1}.
374 */
375 public int getInstallerUID() {
376 return installerUID;
377 }
378
379 // The following setter methods are used to validate the
380 // input field when constructing a ServiceTag instance
381
382 private void setInstanceURN(String instanceURN) {
383 if (instanceURN == null) {
384 throw new NullPointerException("Parameter instanceURN cannot be null");
385 }
386 if (instanceURN.length() > MAX_URN_LEN) {
387 throw new IllegalArgumentException("instanceURN \"" + instanceURN +
388 "\" exceeds maximum length " + MAX_URN_LEN);
389 }
390 this.instanceURN = instanceURN;
391 }
392
393 private void setProductName(String productName) {
394 if (productName == null) {
395 throw new NullPointerException("Parameter productName cannot be null");
396 }
397 if (productName.length() == 0) {
398 throw new IllegalArgumentException("product name cannot be empty");
399 }
400 if (productName.length() > MAX_PRODUCT_NAME_LEN) {
401 throw new IllegalArgumentException("productName \"" + productName +
402 "\" exceeds maximum length " + MAX_PRODUCT_NAME_LEN);
403 }
404 this.productName = productName;
405 }
406
407 private void setProductVersion(String productVersion) {
408 if (productVersion == null) {
409 throw new NullPointerException("Parameter productVersion cannot be null");
410 }
411
412 if (productVersion.length() == 0) {
413 throw new IllegalArgumentException("product version cannot be empty");
414 }
415 if (productVersion.length() > MAX_PRODUCT_VERSION_LEN) {
416 throw new IllegalArgumentException("productVersion \"" +
417 productVersion + "\" exceeds maximum length " +
418 MAX_PRODUCT_VERSION_LEN);
419 }
420 this.productVersion = productVersion;
421 }
422
423 private void setProductURN(String productURN) {
424 if (productURN == null) {
425 throw new NullPointerException("Parameter productURN cannot be null");
426 }
427 if (productURN.length() == 0) {
428 throw new IllegalArgumentException("product URN cannot be empty");
429 }
430 if (productURN.length() > MAX_URN_LEN) {
431 throw new IllegalArgumentException("productURN \"" + productURN +
432 "\" exceeds maximum length " + MAX_URN_LEN);
433 }
434 this.productURN = productURN;
435 }
436
437 private void setProductParentURN(String productParentURN) {
438 if (productParentURN == null) {
439 throw new NullPointerException("Parameter productParentURN cannot be null");
440 }
441 // optional field - can be empty
442 if (productParentURN.length() > MAX_URN_LEN) {
443 throw new IllegalArgumentException("productParentURN \"" +
444 productParentURN + "\" exceeds maximum length " +
445 MAX_URN_LEN);
446 }
447 this.productParentURN = productParentURN;
448 }
449
450 private void setProductParent(String productParent) {
451 if (productParent == null) {
452 throw new NullPointerException("Parameter productParent cannot be null");
453 }
454 if (productParent.length() == 0) {
455 throw new IllegalArgumentException("product parent cannot be empty");
456 }
457 if (productParent.length() > MAX_PRODUCT_PARENT_LEN) {
458 throw new IllegalArgumentException("productParent \"" +
459 productParent + "\" exceeds maximum length " +
460 MAX_PRODUCT_PARENT_LEN);
461 }
462 this.productParent = productParent;
463 }
464
465 void setProductDefinedInstanceID(String productDefinedInstanceID) {
466 if (productDefinedInstanceID == null) {
467 throw new NullPointerException("Parameter productDefinedInstanceID cannot be null");
468 }
469 if (productDefinedInstanceID.length() > MAX_URN_LEN) {
470 throw new IllegalArgumentException("productDefinedInstanceID \"" +
471 productDefinedInstanceID + "\" exceeds maximum length " +
472 MAX_URN_LEN);
473 }
474 // optional field - can be empty
475 this.productDefinedInstanceID = productDefinedInstanceID;
476 }
477
478 private void setProductVendor(String productVendor) {
479 if (productVendor == null) {
480 throw new NullPointerException("Parameter productVendor cannot be null");
481 }
482 if (productVendor.length() == 0) {
483 throw new IllegalArgumentException("product vendor cannot be empty");
484 }
485 if (productVendor.length() > MAX_PRODUCT_VENDOR_LEN) {
486 throw new IllegalArgumentException("productVendor \"" +
487 productVendor + "\" exceeds maximum length " +
488 MAX_PRODUCT_VENDOR_LEN);
489 }
490 this.productVendor = productVendor;
491 }
492
493 private void setPlatformArch(String platformArch) {
494 if (platformArch == null) {
495 throw new NullPointerException("Parameter platformArch cannot be null");
496 }
497 if (platformArch.length() == 0) {
498 throw new IllegalArgumentException("platform architecture cannot be empty");
499 }
500 if (platformArch.length() > MAX_PLATFORM_ARCH_LEN) {
501 throw new IllegalArgumentException("platformArch \"" +
502 platformArch + "\" exceeds maximum length " +
503 MAX_PLATFORM_ARCH_LEN);
504 }
505 this.platformArch = platformArch;
506 }
507
508 private void setTimestamp(Date timestamp) {
509 // can be null
510 this.timestamp = timestamp;
511 }
512
513 private void setContainer(String container) {
514 if (container == null) {
515 throw new NullPointerException("Parameter container cannot be null");
516 }
517 if (container.length() == 0) {
518 throw new IllegalArgumentException("container cannot be empty");
519 }
520 if (container.length() > MAX_CONTAINER_LEN) {
521 throw new IllegalArgumentException("container \"" +
522 container + "\" exceeds maximum length " +
523 MAX_CONTAINER_LEN);
524 }
525 this.container = container;
526 }
527
528 private void setSource(String source) {
529 if (source == null) {
530 throw new NullPointerException("Parameter source cannot be null");
531 }
532 if (source.length() == 0) {
533 throw new IllegalArgumentException("source cannot be empty");
534 }
535 if (source.length() > MAX_SOURCE_LEN) {
536 throw new IllegalArgumentException("source \"" + source +
537 "\" exceeds maximum length " + MAX_SOURCE_LEN);
538 }
539 this.source = source;
540 }
541
542 private void setInstallerUID(int installerUID) {
543 this.installerUID = installerUID;
544 }
545
546 /**
547 * Compares this service tag to the specified object.
548 * The result is {@code true} if and only if the argument is
549 * not {@code null} and is a {@code ServiceTag} object whose
550 * <tt>instance_urn</tt> is the same as the
551 * <tt>instance_urn</tt> of this service tag.
552 *
553 * @return {@code true} if this service tag is the same as
554 * the specified object.
555 */
556 @Override
557 public boolean equals(Object obj) {
558 if (obj == null || !(obj instanceof ServiceTag)) {
559 return false;
560 }
561 ServiceTag st = (ServiceTag) obj;
562 if (st == this) {
563 return true;
564 }
565 return st.getInstanceURN().equals(getInstanceURN());
566 }
567
568 /**
569 * Returns the hash code value for this service tag.
570 * @return the hash code value for this service tag.
571 */
572 @Override
573 public int hashCode() {
574 int hash = 7;
575 hash = 19 * hash + (this.instanceURN != null ? this.instanceURN.hashCode() : 0);
576 return hash;
577 }
578
579 /**
580 * Returns the string representation of this service tag.
581 * The format is implementation specific.
582 *
583 * @return the string representation of this service tag.
584 */
585 public String toString() {
586 StringBuilder sb = new StringBuilder();
587 sb.append(ST_NODE_INSTANCE_URN).append("=").append(instanceURN).append("\n");
588 sb.append(ST_NODE_PRODUCT_NAME).append("=").append(productName).append("\n");
589 sb.append(ST_NODE_PRODUCT_VERSION).append("=").append(productVersion).append("\n");
590 sb.append(ST_NODE_PRODUCT_URN).append("=").append(productURN).append("\n");
591 sb.append(ST_NODE_PRODUCT_PARENT_URN).append("=").append(productParentURN).append("\n");
592 sb.append(ST_NODE_PRODUCT_PARENT).append("=").append(productParent).append("\n");
593 sb.append(ST_NODE_PRODUCT_DEFINED_INST_ID).append("=").append(productDefinedInstanceID).append("\n");
594 sb.append(ST_NODE_PRODUCT_VENDOR).append("=").append(productVendor).append("\n");
595 sb.append(ST_NODE_PLATFORM_ARCH).append("=").append(platformArch).append("\n");
596 sb.append(ST_NODE_TIMESTAMP).append("=").append(Util.formatTimestamp(timestamp)).append("\n");
597 sb.append(ST_NODE_CONTAINER).append("=").append(container).append("\n");
598 sb.append(ST_NODE_SOURCE).append("=").append(source).append("\n");
599 sb.append(ST_NODE_INSTALLER_UID).append("=").append(String.valueOf(installerUID)).append("\n");
600 return sb.toString();
601 }
602
603
604 /**
605 * Returns the {@link ServiceTag} instance for the running Java
606 * platform. The {@link ServiceTag#setSource source} field
607 * of the {@code ServiceTag} will be set to the given {@code source}.
608 * This method will return {@code null} if there is no service tag
609 * for the running Java platform.
610 * <p>
611 * This method is designed for Sun software that bundles the JDK
612 * or the JRE to use. It is recommended that the {@code source}
613 * string contains information about the bundling software
614 * such as the name and the version of the software bundle,
615 * for example,
616 * <blockquote>
617 * <tt>NetBeans IDE 6.0 with JDK 6 Update 5 Bundle</tt>
618 * </blockquote>
619 * in a NetBeans/JDK bundle.
620 * <p>
621 * At the first time to call this method the application
622 * is required to have the write permission to the installed
623 * directory of this running JDK or JRE instance.
624 *
625 * @param source the source that bundles the JDK or the JRE.
626 * @return a {@code ServiceTag} object for the Java platform,
627 * or {@code null} if not supported.
628 * @throws IOException if an error occurs in this operation.
629 */
630 public static ServiceTag getJavaServiceTag(String source) throws IOException {
631 return Installer.getJavaServiceTag(source);
632 }
633
634 }