/*
* Copyright (c) 2008, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package com.sun.servicetag;
import java.util.Date;
import java.io.IOException;
import static com.sun.servicetag.RegistrationDocument.*;
/**
* A service tag is an XML-based data structure that identifies a product or
* a component on a system. The service tag schema is defined by the
* Service Tags Technology. The location of the DTD file is platform dependent.
* On Solaris, see <tt>/usr/share/lib/xml/dtd/servicetag.dtd</tt>.
* <p>
* A valid {@code ServiceTag} instance must comply to the service tag schema
* and contain the following fields:
* <ul>
* <li>{@link #getInstanceURN <tt>instance_urn</tt>}</li>
* <li>{@link #getProductName <tt>product_name</tt>}</li>
* <li>{@link #getProductVersion <tt>product_version</tt>}</li>
* <li>{@link #getProductURN <tt>product_urn</tt>}</li>
* <li>{@link #getProductParent <tt>product_parent</tt>}</li>
* <li>{@link #getProductParentURN <tt>product_parent_urn</tt>}</li>
* <li>{@link #getProductDefinedInstanceID <tt>product_defined_inst_id</tt>}</li>
* <li>{@link #getProductVendor <tt>product_vendor</tt>}</li>
* <li>{@link #getPlatformArch <tt>platform_arch</tt>}</li>
* <li>{@link #getContainer <tt>container</tt>}</li>
* <li>{@link #getSource <tt>source</tt>}</li>
* <li>{@link #getInstallerUID <tt>installer_uid</tt>}</li>
* <li>{@link #getTimestamp <tt>timestamp</tt>}</li>
* </ul>
*
* The <tt>instance_urn</tt> can be specified when a {@code ServiceTag}
* object is created, or it can be generated when it is added to
* a {@link RegistrationData} object, or {@link Registry
* system service tag registry}. The <tt>installer_uid</tt> and
* <tt>timestamp</tt> are set when a {@code ServiceTag} object
* is added to a {@link RegistrationData} object, or {@link Registry
* system service tag registry}.
*
* @see <a href="https://sunconnection.sun.com/FAQ/sc_faq.html">Service Tags FAQ</a>
*/
public class ServiceTag {
private String instanceURN;
private String productName;
private String productVersion;
private String productURN;
private String productParent;
private String productParentURN;
private String productDefinedInstanceID;
private String productVendor;
private String platformArch;
private String container;
private String source;
private int installerUID;
private Date timestamp;
// Service Tag Field Lengths (defined in sthelper.h)
// Since the constants defined in sthelper.h includes the null-terminated
// character, so minus 1 from the sthelper.h defined values.
private final int MAX_URN_LEN = 256 - 1;
private final int MAX_PRODUCT_NAME_LEN = 256 - 1;
private final int MAX_PRODUCT_VERSION_LEN = 64 - 1;
private final int MAX_PRODUCT_PARENT_LEN = 256 - 1;
private final int MAX_PRODUCT_VENDOR_LEN = 64 - 1;
private final int MAX_PLATFORM_ARCH_LEN = 64 - 1;
private final int MAX_CONTAINER_LEN = 64 - 1;
private final int MAX_SOURCE_LEN = 64 - 1;
// private constructors
private ServiceTag() {
}
// package private
ServiceTag(String instanceURN,
String productName,
String productVersion,
String productURN,
String productParent,
String productParentURN,
String productDefinedInstanceID,
String productVendor,
String platformArch,
String container,
String source,
int installerUID,
Date timestamp) {
setInstanceURN(instanceURN);
setProductName(productName);
setProductVersion(productVersion);
setProductURN(productURN);
setProductParentURN(productParentURN);
setProductParent(productParent);
setProductDefinedInstanceID(productDefinedInstanceID);
setProductVendor(productVendor);
setPlatformArch(platformArch);
setContainer(container);
setSource(source);
setInstallerUID(installerUID);
setTimestamp(timestamp);
}
/**
* Creates a service tag object with no <tt>instance_urn</tt>.
*
* @param productName the name of the product.
* @param productVersion the version of the product.
* @param productURN the uniform resource name of the product
* @param productParent the name of the product's parent.
* @param productParentURN the uniform resource name of the product's parent.
* @param productDefinedInstanceID the instance identifier.
* @param productVendor the vendor of the product.
* @param platformArch the operating system architecture.
* @param container the container of the product.
* @param source the source of the product.
*
* @throws IllegalArgumentException if any value of the input fields
* does not conform to the service tag XML schema.
*/
public static ServiceTag newInstance(String productName,
String productVersion,
String productURN,
String productParent,
String productParentURN,
String productDefinedInstanceID,
String productVendor,
String platformArch,
String container,
String source) {
return new ServiceTag("", /* empty instance_urn */
productName,
productVersion,
productURN,
productParent,
productParentURN,
productDefinedInstanceID,
productVendor,
platformArch,
container,
source,
-1,
null);
}
/**
* Creates a service tag object with a specified <tt>instance_urn</tt>.
*
* @param instanceURN the uniform resource name of this instance.
* @param productName the name of the product.
* @param productVersion the version of the product.
* @param productURN the uniform resource name of the product
* @param productParent the name of the product's parent.
* @param productParentURN the uniform resource name of the product's parent.
* @param productDefinedInstanceID the instance identifier.
* @param productVendor the vendor of the product.
* @param platformArch the operating system architecture.
* @param container the container of the product.
* @param source the source of the product.
*
* @throws IllegalArgumentException if any value of the input fields
* does not conform to the service tag XML schema.
*/
public static ServiceTag newInstance(String instanceURN,
String productName,
String productVersion,
String productURN,
String productParent,
String productParentURN,
String productDefinedInstanceID,
String productVendor,
String platformArch,
String container,
String source) {
return new ServiceTag(instanceURN,
productName,
productVersion,
productURN,
productParent,
productParentURN,
productDefinedInstanceID,
productVendor,
platformArch,
container,
source,
-1,
null);
}
// Creates a copy of the ServiceTag instance
// with instance_urn and timestamp initialized
static ServiceTag newInstanceWithUrnTimestamp(ServiceTag st) {
String instanceURN =
(st.getInstanceURN().length() == 0 ? Util.generateURN() :
st.getInstanceURN());
ServiceTag svcTag = new ServiceTag(instanceURN,
st.getProductName(),
st.getProductVersion(),
st.getProductURN(),
st.getProductParent(),
st.getProductParentURN(),
st.getProductDefinedInstanceID(),
st.getProductVendor(),
st.getPlatformArch(),
st.getContainer(),
st.getSource(),
st.getInstallerUID(),
new Date());
return svcTag;
}
/**
* Returns a uniform resource name (URN) in this format:
* <blockquote>
* "<tt>urn:st:<32-char {@link java.util.UUID uuid}></tt>"
* </blockquote>
* @return a URN.
*/
public static String generateInstanceURN() {
return Util.generateURN();
}
/**
* Returns the uniform resource name of this service tag instance.
*
* @return the <tt>instance_urn</tt> of this service tag.
*/
public String getInstanceURN() {
return instanceURN;
}
/**
* Returns the name of the product.
*
* @return the product name.
*/
public String getProductName() {
return productName;
}
/**
* Returns the version of the product.
*
* @return the product version.
*/
public String getProductVersion() {
return productVersion;
}
/**
* Returns the uniform resource name of the product.
*
* @return the product URN.
*/
public String getProductURN() {
return productURN;
}
/**
* Returns the uniform resource name of the product's parent.
*
* @return the product's parent URN.
*/
public String getProductParentURN() {
return productParentURN;
}
/**
* Returns the name of the product's parent.
*
* @return the product's parent name.
*/
public String getProductParent() {
return productParent;
}
/**
* Returns the identifier defined for this product instance.
*
* @return the identifier defined for this product instance.
*/
public String getProductDefinedInstanceID() {
return productDefinedInstanceID;
}
/**
* Returns the vendor of the product.
*
* @return the product vendor.
*/
public String getProductVendor() {
return productVendor;
}
/**
* Returns the platform architecture on which the product
* is running on.
*
* @return the platform architecture on which the product is running on.
*/
public String getPlatformArch() {
return platformArch;
}
/**
* Returns the timestamp. This timestamp is set when this service tag
* is added to or updated in a {@code RegistrationData} object or
* the system service tag registry.
* This method may return {@code null}.
*
* @return timestamp when this service tag
* is added to or updated in a {@code RegistrationData} object or
* the system service tag registry, or {@code null}.
*/
public Date getTimestamp() {
if (timestamp != null) {
return (Date) timestamp.clone();
} else {
return null;
}
}
/**
* Returns the container of the product.
*
* @return the container of the product.
*/
public String getContainer() {
return container;
}
/**
* Returns the source of this service tag.
*
* @return source of this service tag.
*/
public String getSource() {
return source;
}
/**
* Returns the UID. The UID is set when this service tag
* is added to or updated in the system service tag registry.
* This is platform dependent whose default value is {@code -1}.
* When this service tag is added to a {@code RegistrationData},
* the UID is not set.
*
* @return the UID of whom this service tag
* is added to or updated in the system service tag registry,
* or {@code -1}.
*/
public int getInstallerUID() {
return installerUID;
}
// The following setter methods are used to validate the
// input field when constructing a ServiceTag instance
private void setInstanceURN(String instanceURN) {
if (instanceURN == null) {
throw new NullPointerException("Parameter instanceURN cannot be null");
}
if (instanceURN.length() > MAX_URN_LEN) {
throw new IllegalArgumentException("instanceURN \"" + instanceURN +
"\" exceeds maximum length " + MAX_URN_LEN);
}
this.instanceURN = instanceURN;
}
private void setProductName(String productName) {
if (productName == null) {
throw new NullPointerException("Parameter productName cannot be null");
}
if (productName.length() == 0) {
throw new IllegalArgumentException("product name cannot be empty");
}
if (productName.length() > MAX_PRODUCT_NAME_LEN) {
throw new IllegalArgumentException("productName \"" + productName +
"\" exceeds maximum length " + MAX_PRODUCT_NAME_LEN);
}
this.productName = productName;
}
private void setProductVersion(String productVersion) {
if (productVersion == null) {
throw new NullPointerException("Parameter productVersion cannot be null");
}
if (productVersion.length() == 0) {
throw new IllegalArgumentException("product version cannot be empty");
}
if (productVersion.length() > MAX_PRODUCT_VERSION_LEN) {
throw new IllegalArgumentException("productVersion \"" +
productVersion + "\" exceeds maximum length " +
MAX_PRODUCT_VERSION_LEN);
}
this.productVersion = productVersion;
}
private void setProductURN(String productURN) {
if (productURN == null) {
throw new NullPointerException("Parameter productURN cannot be null");
}
if (productURN.length() == 0) {
throw new IllegalArgumentException("product URN cannot be empty");
}
if (productURN.length() > MAX_URN_LEN) {
throw new IllegalArgumentException("productURN \"" + productURN +
"\" exceeds maximum length " + MAX_URN_LEN);
}
this.productURN = productURN;
}
private void setProductParentURN(String productParentURN) {
if (productParentURN == null) {
throw new NullPointerException("Parameter productParentURN cannot be null");
}
// optional field - can be empty
if (productParentURN.length() > MAX_URN_LEN) {
throw new IllegalArgumentException("productParentURN \"" +
productParentURN + "\" exceeds maximum length " +
MAX_URN_LEN);
}
this.productParentURN = productParentURN;
}
private void setProductParent(String productParent) {
if (productParent == null) {
throw new NullPointerException("Parameter productParent cannot be null");
}
if (productParent.length() == 0) {
throw new IllegalArgumentException("product parent cannot be empty");
}
if (productParent.length() > MAX_PRODUCT_PARENT_LEN) {
throw new IllegalArgumentException("productParent \"" +
productParent + "\" exceeds maximum length " +
MAX_PRODUCT_PARENT_LEN);
}
this.productParent = productParent;
}
void setProductDefinedInstanceID(String productDefinedInstanceID) {
if (productDefinedInstanceID == null) {
throw new NullPointerException("Parameter productDefinedInstanceID cannot be null");
}
if (productDefinedInstanceID.length() > MAX_URN_LEN) {
throw new IllegalArgumentException("productDefinedInstanceID \"" +
productDefinedInstanceID + "\" exceeds maximum length " +
MAX_URN_LEN);
}
// optional field - can be empty
this.productDefinedInstanceID = productDefinedInstanceID;
}
private void setProductVendor(String productVendor) {
if (productVendor == null) {
throw new NullPointerException("Parameter productVendor cannot be null");
}
if (productVendor.length() == 0) {
throw new IllegalArgumentException("product vendor cannot be empty");
}
if (productVendor.length() > MAX_PRODUCT_VENDOR_LEN) {
throw new IllegalArgumentException("productVendor \"" +
productVendor + "\" exceeds maximum length " +
MAX_PRODUCT_VENDOR_LEN);
}
this.productVendor = productVendor;
}
private void setPlatformArch(String platformArch) {
if (platformArch == null) {
throw new NullPointerException("Parameter platformArch cannot be null");
}
if (platformArch.length() == 0) {
throw new IllegalArgumentException("platform architecture cannot be empty");
}
if (platformArch.length() > MAX_PLATFORM_ARCH_LEN) {
throw new IllegalArgumentException("platformArch \"" +
platformArch + "\" exceeds maximum length " +
MAX_PLATFORM_ARCH_LEN);
}
this.platformArch = platformArch;
}
private void setTimestamp(Date timestamp) {
// can be null
this.timestamp = timestamp;
}
private void setContainer(String container) {
if (container == null) {
throw new NullPointerException("Parameter container cannot be null");
}
if (container.length() == 0) {
throw new IllegalArgumentException("container cannot be empty");
}
if (container.length() > MAX_CONTAINER_LEN) {
throw new IllegalArgumentException("container \"" +
container + "\" exceeds maximum length " +
MAX_CONTAINER_LEN);
}
this.container = container;
}
private void setSource(String source) {
if (source == null) {
throw new NullPointerException("Parameter source cannot be null");
}
if (source.length() == 0) {
throw new IllegalArgumentException("source cannot be empty");
}
if (source.length() > MAX_SOURCE_LEN) {
throw new IllegalArgumentException("source \"" + source +
"\" exceeds maximum length " + MAX_SOURCE_LEN);
}
this.source = source;
}
private void setInstallerUID(int installerUID) {
this.installerUID = installerUID;
}
/**
* Compares this service tag to the specified object.
* The result is {@code true} if and only if the argument is
* not {@code null} and is a {@code ServiceTag} object whose
* <tt>instance_urn</tt> is the same as the
* <tt>instance_urn</tt> of this service tag.
*
* @return {@code true} if this service tag is the same as
* the specified object.
*/
@Override
public boolean equals(Object obj) {
if (obj == null || !(obj instanceof ServiceTag)) {
return false;
}
ServiceTag st = (ServiceTag) obj;
if (st == this) {
return true;
}
return st.getInstanceURN().equals(getInstanceURN());
}
/**
* Returns the hash code value for this service tag.
* @return the hash code value for this service tag.
*/
@Override
public int hashCode() {
int hash = 7;
hash = 19 * hash + (this.instanceURN != null ? this.instanceURN.hashCode() : 0);
return hash;
}
/**
* Returns the string representation of this service tag.
* The format is implementation specific.
*
* @return the string representation of this service tag.
*/
public String toString() {
StringBuilder sb = new StringBuilder();
sb.append(ST_NODE_INSTANCE_URN).append("=").append(instanceURN).append("\n");
sb.append(ST_NODE_PRODUCT_NAME).append("=").append(productName).append("\n");
sb.append(ST_NODE_PRODUCT_VERSION).append("=").append(productVersion).append("\n");
sb.append(ST_NODE_PRODUCT_URN).append("=").append(productURN).append("\n");
sb.append(ST_NODE_PRODUCT_PARENT_URN).append("=").append(productParentURN).append("\n");
sb.append(ST_NODE_PRODUCT_PARENT).append("=").append(productParent).append("\n");
sb.append(ST_NODE_PRODUCT_DEFINED_INST_ID).append("=").append(productDefinedInstanceID).append("\n");
sb.append(ST_NODE_PRODUCT_VENDOR).append("=").append(productVendor).append("\n");
sb.append(ST_NODE_PLATFORM_ARCH).append("=").append(platformArch).append("\n");
sb.append(ST_NODE_TIMESTAMP).append("=").append(Util.formatTimestamp(timestamp)).append("\n");
sb.append(ST_NODE_CONTAINER).append("=").append(container).append("\n");
sb.append(ST_NODE_SOURCE).append("=").append(source).append("\n");
sb.append(ST_NODE_INSTALLER_UID).append("=").append(String.valueOf(installerUID)).append("\n");
return sb.toString();
}
/**
* Returns the {@link ServiceTag} instance for the running Java
* platform. The {@link ServiceTag#setSource source} field
* of the {@code ServiceTag} will be set to the given {@code source}.
* This method will return {@code null} if there is no service tag
* for the running Java platform.
* <p>
* This method is designed for Sun software that bundles the JDK
* or the JRE to use. It is recommended that the {@code source}
* string contains information about the bundling software
* such as the name and the version of the software bundle,
* for example,
* <blockquote>
* <tt>NetBeans IDE 6.0 with JDK 6 Update 5 Bundle</tt>
* </blockquote>
* in a NetBeans/JDK bundle.
* <p>
* At the first time to call this method the application
* is required to have the write permission to the installed
* directory of this running JDK or JRE instance.
*
* @param source the source that bundles the JDK or the JRE.
* @return a {@code ServiceTag} object for the Java platform,
* or {@code null} if not supported.
* @throws IOException if an error occurs in this operation.
*/
public static ServiceTag getJavaServiceTag(String source) throws IOException {
return Installer.getJavaServiceTag(source);
}
}