Skip Headers
Oracle® Database JDBC Developer's Guide and Reference
10g Release 2 (10.2)

Part Number B14355-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Feedback

Go to previous page
Previous
Go to next page
Next
View PDF

30 End-To-End Metrics Support

Oracle Java Database Connectivity (JDBC) now supports end-to-end metrics when used with Oracle Database 10g. This chapter discusses end-to-end metric support. It contains the following sections:

30.1 Introduction

JDBC supports four end-to-end metrics, all of which are set on a per-connection basis:

All of these metrics are set on a per-connection basis. All operations on a given connection share the same values. Applications normally set these metrics using Dynamic Monitoring Service (DMS). Although it is also possible to set metrics using JDBC, metrics set using DMS override metrics set using JDBC. To use DMS directly, you must be using a DMS-enabled Java Archive (JAR), which is only available as part of Oracle Application Server.

Table 30-1 lists the maximum size for each end-to-end metric.


Note:

If you are using a DMS-enabled JDBC JAR file, then you must include the JAR file for DMS, dms.jar, in your CLASSPATH. The DMS-enabled JDBC JAR file and the DMS JAR file must come from the same Oracle Database release.

Table 30-1 Maximum Lengths for End-to-End Metrics

Metric Maximum length
ACTION 32
CLIENTID 64
ECID (string component) 64
MODULE 48

When a connection is created, the JDBC drivers check DMS for end-to-end metrics. It only makes this check once during the lifetime of the connection.

If DMS metrics are not set, then JDBC never checks DMS for metrics again. Thereafter, each time JDBC communicates with the database, it sends any updated metric values to the database.

If DMS metrics are set, then JDBC ignores the end-to-end metric application programming interface (API) described in this chapter. Thereafter, each time JDBC communicates with the database, it checks with DMS for updated metric values, and, if it finds them, propagates them to the database.

If no metrics are set, then no metrics are sent to the database.

30.2 JDBC API For End-To-End Metrics

If DMS is not in use, either because a non-DMS JAR is in use or because no metric values were set in DMS, then the JDBC API is used.

The JDBC API defines the following constants and methods on OracleConnection:

To unset the metrics, pass an array of appropriate size with all null values and the value Short.MIN_VALUE as the sequence number.

Example 30-1 illustrates how to use JDBC API for end-to-end metrics.

Example 30-1 Using the JDBC API for End-to-End Metrics

ods.setUrl(
"jdbc:oracle:oci:@(DESCRIPTION=
  (ADDRESS=(PROTOCOL=TCP)(HOST=cluster_alias)
    (PORT=1521))
    (CONNECT_DATA=(SERVICE_NAME=service_name)))");
ods.setUser("scott");
Connection conn = ods.getConnection();  

String metrics[] = new String[OracleConnection.END_TO_END_STATE_INDEX_MAX];
metrics[END_TO_END_ACTION_INDEX] = "Spike";
metrics[END_TO_END_MODULE_INDEX] = "Buffy";
// Set these metrics
conn.setEndToEndMetrics(metrics, (short) 0);
// Do some work
// Update a metric
metrics[END_TO_END_MODULE_INDEX] = "Faith";

conn.setEndToEndMetrics(metrics, (short) 0);
// Retrieve metrics
new String[] newMetrics = conn.getEndToEndMetrics();