ProbeDescription.java revision fb3fb4f3d76d55b64440afd0af72775dfad3bd1d
/*
* 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();
}
}