org.opensolaris.os.dtrace
Class ProbeDescription

java.lang.Object
  extended by org.opensolaris.os.dtrace.ProbeDescription
All Implemented Interfaces:
java.io.Serializable, java.lang.Comparable<ProbeDescription>

public final class ProbeDescription
extends java.lang.Object
implements java.io.Serializable, java.lang.Comparable<ProbeDescription>

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:

    *           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
 
Immutable. Supports persistence using XMLEncoder.

See Also:
Consumer.listProbes(ProbeDescription filter), Serialized Form

Nested Class Summary
static class ProbeDescription.Spec
          Enumerates the provider, module, function, and name fields of a probe description.
 
Field Summary
static ProbeDescription EMPTY
          Instance with empty provider, module, function, and name fields matches all DTrace probes on a system.
 
Constructor Summary
ProbeDescription(int probeID, java.lang.String probeProvider, java.lang.String probeModule, java.lang.String probeFunction, java.lang.String probeName)
          Supports XML persistence.
ProbeDescription(java.lang.String probeName)
          Creates a fully qualified probe description from the name given in the format provider:module:function:name or else a probe description that specifies only the unqualified probe name.
ProbeDescription(java.lang.String probeFunction, java.lang.String probeName)
          Creates a probe description that specifies the probe name qualified only by the function name.
ProbeDescription(java.lang.String probeModule, java.lang.String probeFunction, java.lang.String probeName)
          Creates a probe description that specifies the probe name qualified by the function name and module name.
ProbeDescription(java.lang.String probeProvider, java.lang.String probeModule, java.lang.String probeFunction, java.lang.String probeName)
          Creates a fully qualified probe description.
 
Method Summary
 int compareTo(ProbeDescription p)
          Defines the natural ordering of probe descriptions.
 boolean equals(java.lang.Object o)
          Compares the specified object with this probe description for equality.
 java.lang.String getFunction()
          Gets the function name.
 int getID()
          Gets the probe ID.
 java.lang.String getModule()
          Gets the module name.
 java.lang.String getName()
          Gets the unqualified probe name.
 java.lang.String getProvider()
          Gets the provider name.
 int hashCode()
          Overridden to ensure that equal probe descriptions have equal hashcodes.
 boolean isEmpty()
          Returns true if provider, module, function, and name are all omitted.
static ProbeDescription parse(java.lang.String s)
          Generates a probe description from a string in the same format returned by toString().
 java.lang.String toString()
          Gets the string representation of this probe description.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

EMPTY

public static final ProbeDescription EMPTY
Instance with empty provider, module, function, and name fields matches all DTrace probes on a system.

Constructor Detail

ProbeDescription

public ProbeDescription(java.lang.String probeName)
Creates a fully qualified probe description from the name given in the format provider:module:function:name or else a probe description that specifies only the unqualified probe name.

Parameters:
probeName - either the fully qualified name in the format provider:module:function:name or else (if no colon is present) the unqualified name interpreted as :::probeName
See Also:
ProbeDescription(String probeProvider, String probeModule, String probeFunction, String probeName), parse(String s)

ProbeDescription

public ProbeDescription(java.lang.String probeFunction,
                        java.lang.String probeName)
Creates a probe description that specifies the probe name qualified only by the function name.

See Also:
ProbeDescription(String probeProvider, String probeModule, String probeFunction, String probeName)

ProbeDescription

public ProbeDescription(java.lang.String probeModule,
                        java.lang.String probeFunction,
                        java.lang.String probeName)
Creates a probe description that specifies the probe name qualified by the function name and module name.

See Also:
ProbeDescription(String probeProvider, String probeModule, String probeFunction, String probeName)

ProbeDescription

public ProbeDescription(java.lang.String probeProvider,
                        java.lang.String probeModule,
                        java.lang.String probeFunction,
                        java.lang.String 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.

Parameters:
probeProvider - provider name, may be null or empty to match all providers or use pattern syntax to match multiple providers
probeModule - module name, may be null or empty to match all modules or use pattern syntax to match multiple modules
probeFunction - function name, may be null or empty to match all functions or use pattern syntax to match multiple functions
probeName - unqualified probe name, may be null or empty to match all names or use pattern syntax to match multiple names

ProbeDescription

public ProbeDescription(int probeID,
                        java.lang.String probeProvider,
                        java.lang.String probeModule,
                        java.lang.String probeFunction,
                        java.lang.String probeName)
Supports XML persistence.

Method Detail

parse

public static ProbeDescription parse(java.lang.String s)
                              throws java.text.ParseException
Generates a probe description from a string in the same format returned by toString(). Parses the string from right to left.

 provider:module:function:name
 

Returns:
non-null probe description
Throws:
java.text.ParseException - if 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.
java.lang.NullPointerException - if the given string is null

getID

public int getID()
Gets the probe ID.

Returns:
ID generated from a sequence by the native DTrace library, identifies the probe among all probes on the system

getProvider

public java.lang.String getProvider()
Gets the provider name.

Returns:
non-null provider name, may be an empty string to indicate omission

getModule

public java.lang.String getModule()
Gets the module name.

Returns:
non-null module name, may be an empty string to indicate omission

getFunction

public java.lang.String getFunction()
Gets the function name.

Returns:
non-null function name, may be an empty string to indicate omission

getName

public java.lang.String getName()
Gets the unqualified probe name.

Returns:
non-null probe name, may be an empty string to indicate omission

isEmpty

public boolean isEmpty()
Returns true if provider, module, function, and name are all omitted. An empty probe description matches all DTrace probes on a system.

Returns:
true if all probe fields are omitted, false otherwise

equals

public boolean equals(java.lang.Object o)
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 null or empty string was used to indicate omission.

Overrides:
equals in class java.lang.Object
Returns:
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 String.equals()

compareTo

public int compareTo(ProbeDescription p)
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 String.equals(). It makes no difference if null or empty string is used to indicate omission. The behavior is consistent with the equals() method.

Specified by:
compareTo in interface java.lang.Comparable<ProbeDescription>
Returns:
-1, 0, or 1 as this probe description is less than, equal to, or greater than the given probe description

hashCode

public int hashCode()
Overridden to ensure that equal probe descriptions have equal hashcodes.

Overrides:
hashCode in class java.lang.Object

toString

public java.lang.String toString()
Gets the string representation of this probe description. The format is as follows:

 provider:module:function:name
 
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.

Overrides:
toString in class java.lang.Object