Using the Metadata Service

8.1 Introduction to Using the Metadata Service

Oracle Enterprise Scheduler provides the Metadata Service and exposes it to your application program as a Stateless Session Enterprise Java Bean (EJB). The Metadata Service allows you to create, update and manage application-level metadata objects.

The Metadata Service uses Oracle Metadata Services (MDS) to save metadata objects to a repository (the repository can be either database based or file based). The Metadata Service allows you to reuse application-level metadata across multiple job request submissions.

Oracle Enterprise Scheduler metadata objects include the following:

Application Level Metadata: You use the Metadata Service to store job type, job definition, job set, and other application-level metadata object definitions for job requests.
Default (global) Oracle Enterprise Scheduler Metadata: The global Oracle Enterprise Scheduler metadata includes administrative objects such as schedules, workshifts and work assignments. Oracle Enterprise Scheduler provides MetadataServiceMXBean and the MetadataServiceMXBeanProxy to access and store default administrative objects

Note:

Oracle Enterprise Scheduler metadata objects are used both in application-level metadata and in global metadata

Access to application level-metadata objects is exposed only with the MetadataService interface. The MetadataService is exposed as a stateless session EJB. External clients must access the service only through the corresponding EJB. Clients should not interact with the internal API layer directly. When an application client uses the metadata service through the stateless session EJB, all the methods in this interface accept a reference to a MetadataServiceHandle argument, which stores state across multiple calls, for example when multiple methods are to be called within a user transaction. The MBeanProxy interface does not require a handle.

In an Oracle Enterprise Scheduler application you do not need to access or manipulate the MetadataServiceHandle. The application must hold on to the reference created by the open method and pass it in methods being called. Finally the handle must explicitly be closed by calling the close method. Only upon calling the close method are any changes made using a given handle be committed (or aborted).

Metadata object names must be unique within the scope of a given package or name space. Within a given package, two metadata objects with the same name and of the same type cannot be created.

8.1.1 Introduction to Metadata Service Name Spaces

Each Oracle WebLogic Server domain generally includes one metadata repository. A metadata repository is divided into a number of partitions, where each partition is independent and isolated from the others in the repository.

Each application can choose which partition to use. Two applications can also choose to share a partition.

Within a partition, you can organize the data in any way. Usually, the data is organized hierarchically like the file system of an operating system. Where a file system uses folders or directories, the Metadata Service uses name spaces or package names which form a unique name used to locate a file.

For all other Oracle Enterprise Scheduler applications, the application name and an optional package name containing the application-level metadata displays under the name space /oracle/apps/ess. For example, the metadata repository for an application named application1 can be divided into packages with the names dev, test, and production.

The metadata repository for this application has the following structure:

/oracle/apps/ess/application1/dev/metadata
/oracle/apps/ess/application1/test/metadata
/oracle/apps/ess/application1/production/metadata

Each Metadata Service method that creates a metadata object takes a required packageName argument that specifies the package part of the directory structure.

8.1.2 Introduction to Metadata Service Operations

After you access an Oracle Enterprise Scheduler metadata repository you can perform different types of Metadata Service operations, including:

Add, Update, Delete: These operations have transactional characteristics.
Copy: These operations have transactional characteristics.
Query: These operations have read-only characteristics and let you list metadata objects in the metadata repository.
Get: These operations have either read-only or transactional characteristics, depending on the value of the forUpdate flag.

8.1.3 Introduction to Metadata Service Transactions

Because clients access the Metadata Service through a Stateless Session EJB, each method uses a reference to a MetadataServiceHandle argument; this argument stores state for Metadata Service operations. The Metadata Service open() method begins each metadata repository user transaction. In an Oracle Enterprise Scheduler application client you obtain a MetadataServiceHandle reference with the open() method and you pass the reference to subsequent Metadata Service methods. The MetadataServiceHandle reference provides a connection to the metadata repository for the calling application.

In a client application that uses the Metadata Service you must explicitly close a Metadata Service transaction by calling close(). This ends the transaction and causes the transaction to be committed or rolled back (undone). The close() not only controls the transactional behavior within the Metadata Service, but it also allows Oracle Enterprise Scheduler to release certain resources. Thus, the close() is also required for Metadata Service read-only query() and get() operations.

Note:

The Metadata Service does not support JTA global transactions, but you can still make Metadata Service calls in the boundary of your transactions. While you can make Metadata Service calls in bean/container managed transactions, the calls are not part of your transaction.

8.2 Accessing the Metadata Service

There are several ways to access the Metadata Service.

To access the Metadata Service:

Stateless Session EJB access: Use this type of access with Oracle Enterprise Scheduler user applications.
MBean access: This access is intended for use by applications that perform administrative functions using the oracle.as.scheduler.management APIs.
MBean proxy access: This access is intended for use by applications that perform administrative functions using the oracle.as.scheduler.management APIs. Use the MBean proxy if the administrative client is remote to the Oracle Enterprise Scheduler.

8.2.1 How to Access the Metadata Service with a Stateless Session EJB

User applications use a Stateless Session EJB to access the Metadata Service for application level metadata operations. Using JNDI you can lookup the Metadata Service associated with an Oracle Enterprise Scheduler application.

Example 8-1 shows the JNDI lookup for the Oracle Enterprise Scheduler Metadata Service that allows you to use application level metadata. Note that the getMetadataServiceEJB() method looks up the metadata service using the name "ess/metadata". By convention, Oracle Enterprise Scheduler applications use "ess/metadata" for the EJB reference to the MetadataServiceBean.

Example 8-1 JNDI Lookup for Stateless Session EJB Access to Metadata Service

// Demonstration on how to lookup metadata service from a Java EE application
// JNDI lookup on the metadata service EJB

import oracle.as.scheduler.core.JndiUtil;

MetadataService ms = JndiUtil.getMetadataServiceEJB();

8.3 Accessing the Metadata Service with Oracle JDeveloper

Using Oracle JDeveloper at design time you can create, view, and update application level metadata objects.

8.4 Querying Metadata Using the Metadata Service

The Metadata Service query methods let you view objects in the metadata repository.

You can query job types with the queryJobTypes() method, query job definitions with queryJobDefinitions() method, and likewise you can query other metadata objects using the corresponding MetadataService query method.

Associated with a query you can use a filter to restrict the output to obtain only items of interest (in a manner similar to using a SQL WHERE clause).

8.4.1 How to Create a Filter

A filter specifies a comparison or a criteria for a query. You create a filter by creating a comparison that includes a field argument (String), a comparator, and an associated value (Object). In a filter, you can use the filter methods to combine comparisons to form filter expressions.

Table 8-1 lists the comparison operators (comparator argument).

Table 8-1 Filter Comparison Operators

Comparison Operator	Description
`CONTAINS`	Field contains the specified value
`ENDS_WITH`	Field ends with the specified value
`EQUALS`	Field equals the specified value
`GREATER_THAN`	Field is greater than the specified value
`GREATER_THAN_EQUALS`	Field is greater than or equal to the specified value
`LESS_THAN`	Field is less than the specified value
`LESS_THAN_EQUALS`	Field is less than or equal to the specified value
`NOT_CONTAINS`	Field does not contain the specified value
`NOT_EQUALS`	Field does not equal the specified value
`STARTS_WITH`	Field starts with the specified value

Example 8-2 shows code that creates a new filter.

Table 8-2 MetadataService Query Fields

Query Field	Description
`MetadataService.QueryField.PACKAGE`	The name of the package.
`MetadataService.QueryField.NAME`	The job definition name.
`MetadataService.QueryField.JOBTYPE`	The job type associated with the job definition.
`MetadataService.QueryField.EXECUTIONTYPE`	The type of job execution, synchronous or asynchronous.
`MetadataService.QueryField.REQUEST_CATEGORY`	The name of the request category.
`MetadataService.QueryField.EXECUTIONMODE`	The mode of job set execution, parallel or serial.
`MetadataService.QueryField.FIRSTSTEP`	The first step in a job set.
`MetadataService.QueryField.ACTIVE`	Indicates whether a work assignment is active.
`MetadataService.QueryField.PRODUCT`	Indicates the name of the product with which the job is associated.
`MetadataService.QueryField.EFFECTIVEAPPLICATION`	The name of the hosting application wherein this job should run.
`MetadataService.QueryField.LOGICAL_CLUSTER_NAME`	The logical cluster associated with the job.

Example 8-2 Creating a Filter with a Filter Comparator for a Query

Filter filter =
  new Filter(MetadataService.QueryField.PACKAGE.fieldName(),
  Filter.Comparator.NOT_EQUALS, null);

8.4.2 How to Query Metadata Objects

A MetadataService query returns an enumeration list of MetadataObjectIDs of the form:

java.util.Enumeration<MetadataObjectId>

Example 8-3 shows a sample routine that queries for a list of job types in the metadata.

Example 8-3, shows the following important steps for using the queryJobTypes() method:

You need to supply a reference to a metadata repository by obtaining an instance of MetadataServiceHandle.
You need to create a filter for the query. The filter contains the fields, comparators, and values to search for.
You determine the field to sort by in the query using the orderBy argument, or you set the orderBy argument to null to indicate that no specific ordering is applied.
You set the ascending argument for the query. When ordering is applied setting the ascending argument to true indicates ascending order or false indicates descending order for the result list.

Example 8-3 Using Metadata Service Query Methods

Enumeration<MetadataObjectId> qryResults
            = m_service.queryJobTypes(handle, filter, null, false);