com.sun.sgs.profile
Interface ProfileCollector

All Known Implementing Classes:

ProfileCollectorImpl

public interface ProfileCollector

This is the main aggregation point for profiling data. Implementations of this interface are used to collect data from arbitrary sources (typically ProfileConsumers or the scheduler itself) and keep track of which tasks are generating which data.

This interface allows instances of ProfileListener to register as listeners for reported data. All reporting to these listeners is done synchronously, such that listeners do not need to worry about being called concurrently. Listeners should be efficient in handling reports, since they may be blocking all other listeners.

Nested Class Summary

static class

ProfileCollector.ProfileLevel The profiling levels.

Method Summary

void	addListener(ProfileListener listener, boolean canRemove) Adds a ProfileListener as a listener for profiling data reports.
void	addListener(String listenerClassName) Instantiates and adds a ProfileListener.
ProfileConsumer	getConsumer(String name) Returns the named ProfileConsumer, or creates a new one with that name.
Map<String,ProfileConsumer>	getConsumers() Returns a read-only map of ProfileConsumer names to the ProfileConsumers which have been created through a call to getConsumer.
ProfileCollector.ProfileLevel	getDefaultProfileLevel() Gets the default system profiling level, which is the default level for any newly created ProfileConsumer.
List<ProfileListener>	getListeners() Returns a read-only list of ProfileListeners which have been added.
Object	getRegisteredMBean(String mBeanName) Returns the object registered under the given name, or null if no object has been registered with that name.
void	registerMBean(Object mBean, String mBeanName) Registers the given MBean with the current VM's platform MBean server, allowing it to be monitored by tools like JConsole.
void	removeListener(ProfileListener listener) Removes a ProfileListener and calls ProfileListener.shutdown() on the listener.
void	setDefaultProfileLevel(ProfileCollector.ProfileLevel level) Sets the default profile level, used as the initial level when creating new ProfileConsumers.
void	shutdown() Shuts down the ProfileCollector, reclaiming resources as necessary.

Method Detail

getDefaultProfileLevel

ProfileCollector.ProfileLevel getDefaultProfileLevel()

Gets the default system profiling level, which is the default level for any newly created ProfileConsumer.

Returns:

the default profiling level

setDefaultProfileLevel

void setDefaultProfileLevel(ProfileCollector.ProfileLevel level)

Sets the default profile level, used as the initial level when creating new ProfileConsumers.

Parameters:

level - the new default profile level

shutdown

void shutdown()

Shuts down the ProfileCollector, reclaiming resources as necessary.

addListener

void addListener(ProfileListener listener,
                 boolean canRemove)

Adds a ProfileListener as a listener for profiling data reports. The listener is immediately updated on the current set of operations and the number of scheduler threads. The listener can be marked as unable to be removed by removeListener or shutdown by shutdown(); if these operations are performed on a listener that does not allow them, they are silently ignored.

Parameters:

listener - the ProfileListener to add

canRemove - true if this listener can be removed or shut down by the ProfileCollector. This parameter should usually be set to true.

addListener

void addListener(String listenerClassName)
                 throws Exception

Instantiates and adds a ProfileListener. The listener must implement a constructor of the form (java.util.Properties, com.sun.sgs.kernel.TaskOwner, com.sun.sgs.kernel.ComponentRegistry). The listener is immediately updated on the current set of operations and the number of scheduler threads.

Parameters:

listenerClassName - the fully qualified class name of the listener to instantiate and add.

Throws:

Exception - if any were generated during instantiation

getListeners

List<ProfileListener> getListeners()

Returns a read-only list of ProfileListeners which have been added.

Returns:

the list of listeners

removeListener

void removeListener(ProfileListener listener)

Removes a ProfileListener and calls ProfileListener.shutdown() on the listener. If the listener has never been added with addListener, no action is taken.

Parameters:

listener - the listener to remove

getConsumer

ProfileConsumer getConsumer(String name)

Returns the named ProfileConsumer, or creates a new one with that name.

Note that the name must be unique for a new ProfileConsumer to be created. Consumers created by the core server packages have a prefix of com.sun.sgs. to distinguish their namespace. Consumers created by code outside of the core server packages should create their own unique namespace.

Calling getConsumers() will return a map keyed by names already in use.

Parameters:

name - the unique name of the profile consumer

Returns:

a ProfileConsumer with the given name

getConsumers

Map<String,ProfileConsumer> getConsumers()

Returns a read-only map of ProfileConsumer names to the ProfileConsumers which have been created through a call to getConsumer.

Returns:

the map of names to consumers

registerMBean

void registerMBean(Object mBean,
                   String mBeanName)
                   throws JMException

Registers the given MBean with the current VM's platform MBean server, allowing it to be monitored by tools like JConsole.

Parameters:

mBean - the MBean or MXBean to be registered

mBeanName - the name under which it should be registered

Throws:

JMException - if there were any problems reported by the JMX system during registration, including if an object has already been registered with the mBeanName

getRegisteredMBean

Object getRegisteredMBean(String mBeanName)

Returns the object registered under the given name, or null if no object has been registered with that name.

Parameters:

mBeanName - the name the object was registered under

Returns:

the object passed into registerMBean with the given mBeanName