os/dtrace/ProbeDescription.java

/*
 * CDDL HEADER START
 *
 * The contents of this file are subject to the terms of the
 * Common Development and Distribution License (the "License").
 * You may not use this file except in compliance with the License.
 *
 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
 * or http://www.opensolaris.org/os/licensing.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
 * If applicable, add the following below this CDDL HEADER, with the
 * fields enclosed by brackets "[]" replaced with your own identifying
 * information: Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
 */

/*
 * Copyright 2006 Sun Microsystems, Inc.  All rights reserved.
 * Use is subject to license terms.
 *
 * ident	"%Z%%M%	%I%	%E% SMI"
 */
package org.opensolaris.os.dtrace;

import java.util.*;
import java.text.ParseException;
import java.io.*;
import java.beans.*;

/**
 * A DTrace probe description consists of provider, module, function,
 * and name.  A single probe description may identify a single DTrace
 * probe or match multiple probes.  Any field may be wildcarded by
 * omission (set to null) or set to a glob-style pattern:
 * <pre>
 *    *		Matches any string, including the null string
 *    ?		Matches any single character
 *    [ ... ]	Matches any one of the enclosed characters. A pair of
 *    			characters separated by - matches any character
 *    			between the pair, inclusive. If the first
 *    			character after the [ is !, any character not
 *    			enclosed in the set is matched.
 *    \		Interpret the next character as itself, without any
 *    			special meaning
 * </pre>
 * Immutable.  Supports persistence using {@link java.beans.XMLEncoder}.
 *
 * @see Consumer#listProbes(ProbeDescription filter)
 *
 * @author Tom Erickson
 */
public final class ProbeDescription implements Serializable,
        Comparable <ProbeDescription>
{
    static final long serialVersionUID = 5978023304364513667L;

    /**
     * Instance with empty provider, module, function, and name fields
     * matches all DTrace probes on a system.
     */
    public static final ProbeDescription EMPTY =
	    new ProbeDescription(null, null, null, null);

    private static final int ID_NONE = -1;

    /**
     * Enumerates the provider, module, function, and name fields of a
     * probe description.
     */
    public enum Spec {
	/** Probe provider */
	PROVIDER,
	/** Probe module */
	MODULE,
	/** Probe function */
	FUNCTION,
	/** Probe name (unqualified) */
	NAME
    };

    static {
	try {
	    BeanInfo info = Introspector.getBeanInfo(ProbeDescription.class);
	    PersistenceDelegate persistenceDelegate =
		    new DefaultPersistenceDelegate(
		    new String[] {"id", "provider", "module",
		    "function", "name"});
	    BeanDescriptor d = info.getBeanDescriptor();
	    d.setValue("persistenceDelegate", persistenceDelegate);
	} catch (IntrospectionException e) {
	    System.out.println(e);
	}
    }

    /** @serial */
    private int id = ID_NONE; // set by native code

    /** @serial */
    private final String provider;
    /** @serial */
    private final String module;
    /** @serial */
    private final String function;
    /** @serial */
    private final String name;

    /**
     * Creates a probe description that specifies only the unqualified
     * probe name.
     *
     * @see ProbeDescription#ProbeDescription(String probeProvider,
     * String probeModule, String probeFunction, String probeName)
     */
    public
    ProbeDescription(String probeName)
    {
	this(null, null, null, probeName);
    }

    /**
     * Creates a probe description that specifies the probe name
     * qualified only by the function name.
     *
     * @see ProbeDescription#ProbeDescription(String probeProvider,
     * String probeModule, String probeFunction, String probeName)
     */
    public
    ProbeDescription(String probeFunction, String probeName)
    {
	this(null, null, probeFunction, probeName);
    }

    /**
     * Creates a probe description that specifies the probe name
     * qualified by the function name and module name.
     *
     * @see ProbeDescription#ProbeDescription(String probeProvider,
     * String probeModule, String probeFunction, String probeName)
     */
    public
    ProbeDescription(String probeModule, String probeFunction,
	    String probeName)
    {
	this(null, probeModule, probeFunction, probeName);
    }

    /**
     * Creates a fully qualified probe description.  If no pattern
     * syntax is used and no field is omitted, the resulting description
     * matches at most one DTrace probe.
     *
     * @param probeProvider provider name, may be null or empty to match
     * all providers or use pattern syntax to match multiple providers
     * @param probeModule module name, may be null or empty to match all
     * modules or use pattern syntax to match multiple modules
     * @param probeFunction function name, may be null or empty to match
     * all functions or use pattern syntax to match multiple functions
     * @param probeName unqualified probe name, may be null or empty to
     * match all names or use pattern syntax to match multiple names
     */
    public
    ProbeDescription(String probeProvider,
	    String probeModule,
	    String probeFunction,
	    String probeName)
    {
	provider = ((probeProvider == null) ? "" : probeProvider);
	module = ((probeModule == null) ? "" : probeModule);
	function = ((probeFunction == null) ? "" : probeFunction);
	name = ((probeName == null) ? "" : probeName);
    }

    /**
     * Supports XML persistence.
     */
    public
    ProbeDescription(int probeID,
	    String probeProvider,
	    String probeModule,
	    String probeFunction,
	    String probeName)
    {
	this(probeProvider, probeModule, probeFunction, probeName);
	id = probeID;
    }

    /**
     * Generates a probe description from a string in the same format
     * returned by {@link #toString()}.  Parses the string from right to
     * left.
     * <pre><code>
     * <i>provider:module:function:name</i>
     * </code></pre>
     *
     * @return non-null probe description
     * @throws ParseException if {@code s} does not have the expected
     * format.  The error offset is the index of the first unexpected
     * character encountered starting from the last character and
     * reading backwards.
     * @throws NullPointerException if the given string is {@code null}
     */
    public static ProbeDescription
    parse(String s) throws ParseException
    {
	ProbeDescription p;

	// StringTokenizer and String.split() do not correctly handle
	// the case of consecutive delimiters
	List <String> list = new ArrayList <String> ();
	int len = s.length();
	int npos = len;
	char ch;
	for (int i = (len - 1); i >= 0; --i) {
	    ch = s.charAt(i);
	    if (ch == ':') {
		list.add(0, s.substring((i + 1), npos));
		npos = i;
	    }
	}
	list.add(0, s.substring(0, npos));

	switch (list.size()) {
	    case 0:
		p = EMPTY;
		break;
	    case 1:
		p = new ProbeDescription(list.get(0));
		break;
	    case 2:
		p = new ProbeDescription(list.get(0), list.get(1));
		break;
	    case 3:
		p = new ProbeDescription(list.get(0), list.get(1),
			list.get(2));
		break;
	    case 4:
		p = new ProbeDescription(list.get(0), list.get(1),
			list.get(2), list.get(3));
		break;
	    default:
		// get error offset (parsing right-to-left)
		int offset = (s.length() - 4);
		len = list.size();
		for (int i = (len - 1); i >= (len - 4); --i) {
		    offset -= list.get(i).length();
		}
		throw new ParseException("Overspecified probe " +
			"description: \"" + s + "\"", offset);
	}
	return p;
    }

    /**
     * Gets the probe ID.
     *
     * @return ID generated from a sequence by the native DTrace
     * library, identifies the probe among all probes on the system
     */
    public int
    getID()
    {
	return id;
    }

    /**
     * Gets the provider name.
     *
     * @return non-null provider name, may be an empty string to
     * indicate omission
     */
    public String
    getProvider()
    {
	return provider;
    }

    /**
     * Gets the module name.
     *
     * @return non-null module name, may be an empty string to indicate
     * omission
     */
    public String
    getModule()
    {
	return module;
    }

    /**
     * Gets the function name.
     *
     * @return non-null function name, may be an empty string to
     * indicate omission
     */
    public String
    getFunction()
    {
	return function;
    }

    /**
     * Gets the unqualified probe name.
     *
     * @return non-null probe name, may be an empty string to indicate
     * omission
     */
    public String
    getName()
    {
	return name;
    }

    /**
     * Returns {@code true} if provider, module, function, and name are
     * all omitted.  An empty probe description matches all DTrace
     * probes on a system.
     *
     * @return {@code true} if all probe fields are omitted, {@code
     * false} otherwise
     */
    public boolean
    isEmpty()
    {
	if (provider.length() > 0) {
	    return false;
	}
	if (module.length() > 0) {
	    return false;
	}
	if (function.length() > 0) {
	    return false;
	}
	if (name.length() > 0) {
	    return false;
	}
	return true;
    }

    /**
     * Compares the specified object with this probe description for
     * equality.  Defines equality as having the same fields.  Omitted
     * fields must be omitted in both instances in order for them to be
     * equal, but it makes no difference whether {@code null} or empty
     * string was used to indicate omission.
     *
     * @return {@code true} if and only if all corresponding fields of
     * both probe descriptions are either both omitted (null or empty)
     * or else equal as defined by {@link String#equals(Object o)
     * String.equals()}
     */
    public boolean
    equals(Object o)
    {
	if (o instanceof ProbeDescription) {
	    ProbeDescription p = (ProbeDescription)o;
	    if ((id == ID_NONE) || (p.id == ID_NONE)) {
		return (compareTo(p) == 0);
	    } else {
		return (id == p.id);
	    }
	}

	return false;
    }

    /**
     * Defines the natural ordering of probe descriptions.  Returns the
     * natural ordering of the first unequal pair of corresponding
     * fields (starting with the provider and continuing to the
     * unqualified name only if all other fields are equal).
     * Corresponding fields are equal if they are both omitted or both
     * equal as defined by {@link String#equals(Object o)
     * String.equals()}.  It makes no difference if {@code null} or
     * empty string is used to indicate omission.  The behavior is
     * consistent with the {@link #equals(Object o) equals()} method.
     *
     * @return -1, 0, or 1 as this probe description is less than, equal
     * to, or greater than the given probe description
     */
    public int
    compareTo(ProbeDescription p)
    {
	int cmp = 0;
	cmp = provider.compareTo(p.provider);
	if (cmp == 0) {
	    cmp = module.compareTo(p.module);
	    if (cmp == 0) {
		cmp = function.compareTo(p.function);
		if (cmp == 0) {
		    cmp = name.compareTo(p.name);
		}
	    }
	}
	return (cmp);
    }

    /**
     * Overridden to ensure that equal probe descriptions have equal
     * hashcodes.
     */
    @Override
    public int
    hashCode()
    {
	int hash = id;
	if (hash != ID_NONE) {
	    return hash;
	}

	hash = 17;
	hash = (37 * hash) + provider.hashCode();
	hash = (37 * hash) + module.hashCode();
	hash = (37 * hash) + function.hashCode();
	hash = (37 * hash) + name.hashCode();
	return hash;
    }

    private void
    readObject(ObjectInputStream s)
            throws IOException, ClassNotFoundException
    {
	s.defaultReadObject();
	// check invariants
	if (provider == null) {
	    throw new InvalidObjectException("provider is null");
	}
	if (module == null) {
	    throw new InvalidObjectException("module is null");
	}
	if (function == null) {
	    throw new InvalidObjectException("function is null");
	}
	if (name == null) {
	    throw new InvalidObjectException("name is null");
	}
    }

    /**
     * Gets the string representation of this probe description.  The
     * format is as follows:
     * <pre><code>
     * <i>provider:module:function:name</i>
     * </code></pre>
     * Individual fields may be empty, but none of the three delimiting
     * colons is ever omitted.  If this instance uses pattern matching
     * syntax to match multiple probes, that syntax is preserved in the
     * string representation.
     */
    public String
    toString()
    {
	StringBuffer buf = new StringBuffer();
	buf.append(provider);
	buf.append(':');
	buf.append(module);
	buf.append(':');
	buf.append(function);
	buf.append(':');
	buf.append(name);
	return buf.toString();
    }
}