com.sun.management.oss.pm.measurement
Interface PerformanceMonitorValue

All Superinterfaces:
AttributeAccess, java.lang.Cloneable, ManagedEntityValue, java.io.Serializable, SerializerFactory
All Known Subinterfaces:
PerformanceMonitorByClassesValue, PerformanceMonitorByObjectsValue

public interface PerformanceMonitorValue
extends ManagedEntityValue

This interface is the base value representation of a measurement job.

The JVTPerformanceMonitorSession manages measurement jobs. A client can create and retrieve measurement jobs indirectly by using the methods of an JVTPerformanceMonitorSession.

The granularity period is the time between the initiation of two successive gatherings of measurement data within the timeframe specified in the scheduling attributes.

The reporting mode is used to specify the reporting method of the measurement result reports of the measurement job. The reporting mode can be either file or event or both. If the reporting mode is set to event the system will emit an event that carries the measurement result reports. If the reporting mode is set to file, the measurement job will capture the measurement result reports into a data storage and then emit an event to the client about the availability of the data. The frequency of these events is determined by the reporting period of the job. If the reporting mode is set to both file and event both ways applies. When a client receives an event of data availability, the client can retrieve the data, by using the URL to make a connection to the system. If reporting mode is set to ReportMode.FILE_SINGLE or ReportMode.FILE_SINGLE, the reporting period specifies how often events will be generated.

The report format defines the format of the result reports to be generated. If the report mode is set to ReportMode.FILE_MULTIPLE or EVENT_MULTIPLE the client should not set the report format, it will be assigned by the server.

The measurement schedule specifies the time frames during which the measurement job will be active. The measurement job is active as soon as the start time - if supplied in the schedule - is reached. The system shall support a measurement job start time of up to at least 30 days from the measurement job creation date. If no start time is provided, the measurement job shall become active immediately. The measurement job remains active until the stop time - if supplied in the schedule - is reached. If no measurement job stop time is specified the measurement job will run indefinitely and can only be stopped by system intervention, i.e. by deleting or suspending the measurement job. The time frame defined by the measurement schedule may contain one or more recording intervals. These recording intervals may repeat on a daily and/or weekly basis and specify the time periods during which the measurement data is collected. The start time and end time define a recording interval, which lie between 00.00 and 24.00 hours, aligned on granularity period boundaries. Thus the length of a recording interval will be a multiple of the granularity period. If daily interval is omitted, the measurement job will run continuously through the day. If weekly schedule is omitted the measurement job will run all days of the week. Alternatively the weekly schedule will indicate which days of the week the measurement job will be run. The timer-synchronization between the client and the server is not part of this interface and is left over to the implementers.

The measurement job can have several states: Active and on duty, Active but of duty and suspended. The following shows how the states are changed in accordance to the schedule.

(A) Duration (A schedule represents by startTime and stopTime)

State Transition table (1), the startTime and stopTime is set

 ---------------------++------------------------+
   Time Stream        ||       Operation        |
                      ||     ---suspend()-->    |
                      ||     <--resume()----    |
 ---------------------++-----------+------------+
 1. before startTime  || off-duty  | suspended  |
 ---------------------++-----------+------------+<> startTime
 2. within schedule   || on-duty   | suspended  |
 ---------------------++-----------+------------+<> stopTime
 

State Transition table (2), the startTime is not set and the endTime is set.

 ---------------------++------------------------+
   Time Stream        ||       Operation        |
                      ||     ---suspend()-->    |
                      ||     <--resume()----    |
 ---------------------++-----------+------------+<> startTime not set
 1. within schedule   || on-duty   | suspended  |
 ---------------------++-----------+------------+<> stopTime
 

If startTime is not set means that monitoring will start immediately.

State Transition table (3), the startTime is set and the endTime is not set.

 ---------------------++------------------------+
   Time Stream        ||       Operation        |
                      ||     ---suspend()-->    |
                      ||     <--resume()----    |
 ---------------------++-----------+------------+
 1. before startTime  || off-duty  | suspended  |
 ---------------------++-----------+------------+<> startTime
 2. within schedule   || on-duty   | suspended  |
 ---------------------++-----------+------------+<> forever
 

(B) Daily Scheduling

The daily scheduling is set to have 4 elements, two start times and two stop times.

State Transition table (4)

 ---------------------++------------------------+
   Time Stream        ||       Operation        |
                      ||     ---suspend()-->    |
                      ||     <--resume()----    |
 ---------------------++-----------+------------+
 1. off schedule      || off-duty  | suspended  |
 ---------------------++-----------+------------+<> 1st element
 2. within schedule   || on-duty   | suspended  |
 ---------------------++-----------+------------+<> 2nd element
 3. off schedule      || off-duty  | suspended  |
 ---------------------++-----------+------------+<> 3rd element
 4. within schedule   || on-duty   | suspended  |
 ---------------------++-----------+------------+<> final element
 5. It will be back to 1. because of day-line crossing.
 

(C) Weekly Scheduling

The weekly scheduling is set to Monday and Friday and the daily scheduling is set to have 4 elements, as above.

State Transition table (5)

 ---------------------++------------------------+
   Time Stream        ||       Operation        |
                      ||     ---suspend()-->    |
                      ||     <--resume()----    |
 ---------------------++-----------+------------+
 1. off schedule      || off-duty  | suspended  |
    on Sunday         ||           |            |
 ---------------------++-----------+------------+
 2. off schedule      || off-duty  | suspended  |
    on Monday         ||           |            |
 ---------------------++-----------+------------+<> 1st element
 3. within schedule   || on-duty   | suspended  |
 ---------------------++-----------+------------+<> 2nd element
 4. off schedule      || off-duty  | suspended  |
 ---------------------++-----------+------------+<> 3rd element
 5. within schedule   || on-duty   | suspended  |
 ---------------------++-----------+------------+<> final element
 6. off schedule      || off-duty  | suspended  |
    on Monday         ||           |            |
 ---------------------++-----------+------------+
 7. off schedule      || off-duty  | suspended  |
  on Tuesday-Thursday ||           |            |
 ---------------------++-----------+------------+
 8. off schedule      || off-duty  | suspended  |
    on Friday         ||           |            |
 ---------------------++-----------+------------+<> 1st element
 9. within schedule   || on-duty   | suspended  |
 ---------------------++-----------+------------+<> 2nd element
 10. off schedule     || off-duty  | suspended  |
 ---------------------++-----------+------------+<> 3rd element
 11. within schedule  || on-duty   | suspended  |
 ---------------------++-----------+------------+<> final element
 12. off schedule     || off-duty  | suspended  |
    on Friday         ||           |            |
 ---------------------++-----------+------------+
 13. off schedule     || off-duty  | suspended  |
  on Saturday         ||           |            |
 ---------------------++-----------+------------+
 14. It will be back to 1. because of weekly-line crossing.
 

Version:
0.9, 2001-10-25
Author:
Stefan Aberg
See Also:
JVTPerformanceMonitorSession

Field Summary
static java.lang.String GRANULARITY_PERIOD
          Constant for attribute granularity period.
static java.lang.String NAME
          Constant for attribute measurement name.
static java.lang.String REPORT_BY_EVENT
          Constant for attribute report by event.
static java.lang.String REPORT_BY_FILE
          Constant for attribute report by file.
static java.lang.String REPORT_FORMAT
          Constant for attribute report format.
static java.lang.String REPORTING_PERIOD
          Constant for attribute report period.
static java.lang.String SCHEDULE
          Constant for attribute schedule.
static java.lang.String STATE
          Constant for attribute performance monitor state.
 
Fields inherited from interface com.sun.management.oss.ManagedEntityValue
KEY
 
Method Summary
 int getGranularityPeriod()
          Gets the granularity period of the measurement job.
 java.lang.String getName()
          Returns the name of the measurement job.
 PerformanceMonitorKey getPerformanceMonitorKey()
          Gets the identification key of the measurement job.
 int getReportByEvent()
          Gets the event reporting mode.
 int getReportByFile()
          Gets the file reporting mode.
 ReportFormat getReportFormat()
          Gets the report format of the measurement job.
 int getReportPeriod()
          Returns the reporting period for result report of the measurement job.
 Schedule getSchedule()
          Returns the schedule of the measurement job.
 int getState()
          Gets the state of the measurement job.
 PerformanceMonitorKey makePerformanceMonitorKey()
          Creates a new instance of the PerformanceMonitorKey interface.
 ReportFormat makeReportFormat()
          Creates a new instance of the ReportFormat interface.
 Schedule makeSchedule()
          Creates a new instance of the Schedule interface.
 void setGranularityPeriod(int granularityPeriod)
          Sets the granularity period for the measurement job.
 void setName(java.lang.String name)
          Sets the name of the measurement job.
 void setPerformanceMonitorKey(PerformanceMonitorKey key)
          Sets the identification key of the measurement job.
 void setReportByEvent(int reportMode)
          Sets the event reporting mode.
 void setReportByFile(int reportMode)
          Sets the file reporting mode.
 void setReportFormat(ReportFormat format)
          Sets the report format of the measurement job.
 void setReportPeriod(int period)
          Sets the reporting period of result report of the measurement job.
 void setSchedule(Schedule schedule)
          Sets the schedule of the measurement job.
 void setState(int state)
          Sets the state of the measurement job.
 
Methods inherited from interface com.sun.management.oss.ManagedEntityValue
clone, getLastUpdateVersionNumber, getManagedEntityKey, getSettableAttributeNames, makeManagedEntityKey, setLastUpdateVersionNumber, setManagedEntityKey
 
Methods inherited from interface com.sun.management.oss.AttributeAccess
getAllPopulatedAttributes, getAttributeNames, getAttributeValue, getAttributeValues, getPopulatedAttributeNames, getSupportedOptionalAttributeNames, isFullyPopulated, isPopulated, setAttributeValue, setAttributeValues, unpopulateAllAttributes, unpopulateAttribute
 
Methods inherited from interface com.sun.management.oss.SerializerFactory
getSupportedSerializerTypes, makeSerializer
 

Field Detail

NAME

public static final java.lang.String NAME
Constant for attribute measurement name.

See Also:
Constant Field Values

GRANULARITY_PERIOD

public static final java.lang.String GRANULARITY_PERIOD
Constant for attribute granularity period.

See Also:
Constant Field Values

REPORT_BY_FILE

public static final java.lang.String REPORT_BY_FILE
Constant for attribute report by file.

See Also:
Constant Field Values

REPORT_BY_EVENT

public static final java.lang.String REPORT_BY_EVENT
Constant for attribute report by event.

See Also:
Constant Field Values

REPORTING_PERIOD

public static final java.lang.String REPORTING_PERIOD
Constant for attribute report period.

See Also:
Constant Field Values

REPORT_FORMAT

public static final java.lang.String REPORT_FORMAT
Constant for attribute report format.

See Also:
Constant Field Values

SCHEDULE

public static final java.lang.String SCHEDULE
Constant for attribute schedule.

See Also:
Constant Field Values

STATE

public static final java.lang.String STATE
Constant for attribute performance monitor state.

See Also:
Constant Field Values
Method Detail

getName

public java.lang.String getName()
                         throws java.lang.IllegalStateException
Returns the name of the measurement job.

Returns:
String The name of the measurement job.
Throws:
java.lang.IllegalStateException - Is raised if the attribute is not populated.
See Also:
setName(java.lang.String)

setName

public void setName(java.lang.String name)
             throws java.lang.IllegalArgumentException
Sets the name of the measurement job.

The measurement name will be validated when the value object is passed to the performance monitor bean.

The default value for the name is an empty string.

Parameters:
name - The name of the measurement job.
Throws:
java.lang.IllegalArgumentException - Is raised if the input parameters are not valid.
See Also:
getName()

getGranularityPeriod

public int getGranularityPeriod()
                         throws java.lang.IllegalStateException
Gets the granularity period of the measurement job.

Returns:
int The granularity period in seconds.
Throws:
java.lang.IllegalStateException - Is raised if the attribute is not populated.
See Also:
setGranularityPeriod(int)

setGranularityPeriod

public void setGranularityPeriod(int granularityPeriod)
                          throws java.lang.IllegalArgumentException
Sets the granularity period for the measurement job.

The granularity period is the time between the initiation of two successive gatherings of measurement data, within the timeframe specified in the measurement scheduling. Examples of granularity period can be 5 minutes, 15 minutes, 30 minutes, 1 hour. The granularity period of 5 minutes is used in most cases, but for some measurements it may only make sense to collect data in a larger granularity period.

The granularity period will be validated when the value object is passed to the performance monitor bean.

The granularity period is specified in seconds. The valid granularity periods can be retrieved by calling JVTPerformancMonitorSession.getSupportedGranularities().

Parameters:
granularityPeriod - The granularity period, in seconds, of the measurement job.
Throws:
java.lang.IllegalArgumentException - Is raised if the input parameters are not valid.
See Also:
getGranularityPeriod()

getReportByFile

public int getReportByFile()
                    throws java.lang.IllegalStateException
Gets the file reporting mode.

Returns:
int Returns the file reporting mode.
Throws:
java.lang.IllegalStateException - Is raised if the attribute is not populated.
See Also:
ReportMode, setReportByFile(int)

setReportByFile

public void setReportByFile(int reportMode)
                     throws java.lang.IllegalArgumentException
Sets the file reporting mode.

If the reporting mode is set to file, the measurement job will capture the measurement result reports into a data storage and then emit an event to the client about the availability of the data. The frequency of this event is determined by the reporting period of the job. When the client receives the event of data availability, the client can retrieve the data, by using the URL to make a connection to the system. If the reporting mode is not set to file, no report files will be generated and no corresponding events will be generated.

The default value for file report mode is ReportMode.NO_REPORT_MODE.

Parameters:
reportMode - The file reporting mode.
Throws:
java.lang.IllegalArgumentException - Is raised if the reporting mode is not a file reporting mode.
See Also:
ReportMode, getReportByFile()

getReportByEvent

public int getReportByEvent()
                     throws java.lang.IllegalStateException
Gets the event reporting mode.

Returns:
int Returns the event reporting mode.
Throws:
java.lang.IllegalStateException - Is raised if the attribute is not populated.
See Also:
ReportMode, setReportByEvent(int)

setReportByEvent

public void setReportByEvent(int reportMode)
                      throws java.lang.IllegalArgumentException
Sets the event reporting mode.

If the reporting mode is set to event the system will emit an event that carries the measurement result reports.

The default value for file report mode is ReportMode.NO_REPORT_MODE.

Parameters:
reportMode - The event reporting mode.
Throws:
java.lang.IllegalArgumentException - Is raised if the reporting mode is not a event reporting mode.
See Also:
ReportMode, getReportByEvent()

getReportPeriod

public int getReportPeriod()
                    throws java.lang.IllegalStateException
Returns the reporting period for result report of the measurement job.

Returns:
int Reporting period in number of granularity periods.
Throws:
java.lang.IllegalStateException - Is raised if the attribute is not populated or file report mode is not ReportMode.FILE_SINGLE.
See Also:
setReportPeriod(int)

setReportPeriod

public void setReportPeriod(int period)
                     throws java.lang.IllegalArgumentException
Sets the reporting period of result report of the measurement job.

The reporting period specifies how often measurement result events will be generated and is valid if reporting mode is set to ReportMode.FILE_SINGLE or ReportMode.EVENT_SINGLE.

With the reporting mode set to ReportMode.FILE_SINGLE or ReportMode.EVENT_SINGLE, the reporting period is the number of granularity periods between the initiation of two successive result event generations. The result event shall include (or point to) all data that have been collected since the last result event generation.

If the report period is not set, a value equal to the granularity period of the measurement job is used.

Parameters:
period - Reporting period in number of granularity periods.
Throws:
java.lang.IllegalArgumentException - Is raised if report period is less then zero (0) or the reporting mode not set to ReportMode.FILE_SINGLE.
See Also:
ReportMode, getReportPeriod()

makeReportFormat

public ReportFormat makeReportFormat()
Creates a new instance of the ReportFormat interface.

Returns:
ReportFormat The created object. The object is empty.

getReportFormat

public ReportFormat getReportFormat()
                             throws java.lang.IllegalStateException
Gets the report format of the measurement job.

Returns:
ReportFormat The report format of the measurement job.
Throws:
java.lang.IllegalStateException - Is raised if the attribute is not populated.
See Also:
setReportFormat(com.sun.management.oss.pm.measurement.ReportFormat)

setReportFormat

public void setReportFormat(ReportFormat format)
                     throws java.lang.IllegalArgumentException
Sets the report format of the measurement job.

The report format defines the format of the result reports to be generated. If the report mode is set to ReportMode.FILE_MULTIPLE or EVENT_MULTIPLE the client should not set the report format. In this case the report format is that same as the JVTPerformanceMonitorSession.getCurrentReportFormat()

The supported report format can be retrieved by using the JVTPerformanceMonitorSession.getReportFormats().

Parameters:
format - Report format of the measurement job.
Throws:
java.lang.IllegalArgumentException - Is raised if the input parameters are not valid.
See Also:
getReportFormat()

makeSchedule

public Schedule makeSchedule()
Creates a new instance of the Schedule interface.

Returns:
com.sun.management.oss.pm.util.Schedule The created object. The object is empty.

getSchedule

public Schedule getSchedule()
                     throws java.lang.IllegalStateException
Returns the schedule of the measurement job.

Returns:
com.sun.management.oss.pm.util.Schedule Schedule of the measurement job.
Throws:
java.lang.IllegalStateException - Is raised if the attribute is not populated.
See Also:
setSchedule(com.sun.management.oss.pm.util.Schedule)

setSchedule

public void setSchedule(Schedule schedule)
                 throws java.lang.IllegalArgumentException
Sets the schedule of the measurement job.

The measurement schedule specifies the time frames during which the measurement job will be active. The measurement job is active as soon as the start time - if set - is reached. If no start time is provided, the measurement job shall become active immediately. The measurement job remains active until the stop time - if set - is reached. If no stop time is specified the measurement job will run indefinitely and can only be stopped by system intervention, i.e. by deleting or suspending the measurement job. The time frame defined by the measurement schedule may contain one or more recording intervals. These recording intervals may repeat on weekly basis. If weekly schedule is omitted the measurement job will run all days of the week. Alternatively the weekly schedule will indicate which days of the week the measurement job will be run. The daily schedule of the measurement schedule specifies the time frames during the day which the measurement job will be active. The time frame defined by the measurement schedule may contain one or more recording intervals. These recording intervals specify the time periods during which the measurement data is collected. The start time and end time define a recording interval, which lie between 00.00 and 24.00 hours, aligned on granularity period boundaries. Thus the length of a recording interval will be a multiple of the granularity period. If daily interval is omitted, the measurement job will run continuously through the day.

Parameters:
schedule - Schedule of the measurement job.
Throws:
java.lang.IllegalArgumentException - Is raised if the input parameters are not valid.
See Also:
getSchedule()

getState

public int getState()
             throws java.lang.IllegalStateException
Gets the state of the measurement job.

Returns:
int The state of the measurement job.
Throws:
java.lang.IllegalStateException - Is raised if the attribute is not populated.
See Also:
PerformanceMonitorState, setState(int)

setState

public void setState(int state)
              throws java.lang.IllegalArgumentException
Sets the state of the measurement job.

Parameters:
state - an int specifying the state value
Throws:
java.lang.IllegalArgumentException - Is raised if the state is not a legal state.
See Also:
PerformanceMonitorState, getState()

makePerformanceMonitorKey

public PerformanceMonitorKey makePerformanceMonitorKey()
Creates a new instance of the PerformanceMonitorKey interface.

Returns:
PerformanceMonitorKey The created object. The object is empty.

getPerformanceMonitorKey

public PerformanceMonitorKey getPerformanceMonitorKey()
                                               throws java.lang.IllegalStateException
Gets the identification key of the measurement job.

Returns:
PerformanceMonitorKey The primary key of the measurement job.
Throws:
java.lang.IllegalStateException - Is raised if the attribute is not populated.
See Also:
setPerformanceMonitorKey(com.sun.management.oss.pm.measurement.PerformanceMonitorKey)

setPerformanceMonitorKey

public void setPerformanceMonitorKey(PerformanceMonitorKey key)
                              throws java.lang.IllegalArgumentException
Sets the identification key of the measurement job.

Parameters:
key - a PerformanceMonitorKey object specifying the performance monitor key value
Throws:
java.lang.IllegalArgumentException - Is raised if the input parameters are not valid.
See Also:
getPerformanceMonitorKey()