This chapter describes how to use Oracle Enterprise Scheduler to generate job request logs and output that should be saved for later use by administrators and users.
Logs generated by job requests help administrators diagnose problems and see job-specific status. Logs are accessible through the Fusion Middleware Control. In addition, some jobs generate output as part of their work, such as a report about job-specific data that a user can review after the job has completed. Your code can create and store request log information as well as request output.
This chapter includes the following sections:
Oracle Enterprise Scheduler provides APIs your job can use to request logging. All job types, except for process jobs, use the logging APIs. Oracle Enterprise Scheduler also provides APIs to handle request logs in the content store.
Oracle Enterprise Scheduler supports a single log per request. The log has a name of the form REQUESTID.log. The logging APIs log directly to the content store, and log content may not be rolled back.
For more about viewing job request logs with Fusion Middleware Control, see Viewing Job Request Logs in Oracle Fusion Middleware Administering Oracle Enterprise Scheduler.
The system property SYS_EXT_requestLogLevel constrains which messages logged using the API are stored in the request log.
The property's value defaults to INFO. The complete set of valid values are SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST. Use Java and PL/SQL APIs to discover the request log level.
Note that SYS_EXT_requestLogLevel does not apply to process jobs because they do not use the logging API.
Your logging code writes entries to a log that begins with the following heading information. This header is automatically prefixed to each record written to the log using the logging APIs, therefore it does not apply to process jobs.
####[TIMESTAMP] [LOGLEVEL] Sample log lines: ####[2011-07-11T14:20:32.276-07:00] [INFO] This is a log record. ####[2011-07-11T14:20:32.282-07:00] [INFO] This is the first line of a multi-line log record: second line of multi-line log record.
You can use the Java request logger to log during the execute and update stages of a Java or asynchronous Java job, as well as during pre-processing and post-processing for all job execution types.
The job logic must use the ContentFactory API to get the RequestLogger that can be used to log messages to the request log. Oracle Enterprise Scheduler uses the current value of the SYS_EXT_requestLogLevel system property to constrain logging level each time the logger is retrieved.
In your Java job's logic, you can use the oracle.as.scheduler.request.ContentFactory class getRequestLogger method (see Table 22-1) to get a RequestLogger instance for adding log entries. Note that the request logger does not support a resource bundle.
The Java APIs available for handling logs include the following:
Use the ContentFactory class to get instances of a RequestLogger you can use to create the log and add entries. See Table 22-1.
Use the RequestLogger class to write the log. See Table 22-2.
The oracle.as.scheduler.request.ContentFactory class provides methods to get your code access to the output content framework, as well as to an instance you can use to create the output itself.
Table 22-1 ContentFactory Methods for Creating Request Logs
| Method | Description |
|---|---|
|
Returns a |
After you have a logger instance, you can use the methods in Table 22-2 to add entries.
Table 22-2 RequestLogger Methods for Creating Request Logs
| Method | Description |
|---|---|
|
These methods log messages at the specified levels. The message is logged only if the specified logging level is equal or greater than the log level specified by the When using the log method, the
|
Example 22-1 shows a very simple Java job example that does logging.
Example 22-1 Java Request Logging Example
import oracle.as.scheduler.request.ContentFactory;
import oracle.as.scheduler.request.RequestLogger;
import java.util.logging.Level;
class ExampleJavaLogger{
private boolean m_loggingEnabled = false;
private RequestLogger m_requestLogger = null;
public void execute( RequestExecutionContext ctx,
RequestParameters params )
{
try
{
m_requestLogger = ContentFactory.getRequestLogger(ctx.getRequestId());
m_loggingEnabled = true;
}
catch (Exception ex)
{
// failed to get request logger
}
log(Level.INFO, "Starting the job.");
// ...
log(Level.INFO, "Ending the job.");
}
private void log( Level level, String message )
{
if (m_loggingEnabled)
{
m_requestLogger.log(level, message);
}
}
}
To create logs from PL/SQL, your code can use the ESS_JOB PL/SQL package to write log entries.
Oracle Enterprise Scheduler provides the ESS_JOB package with functions and procedures for logging from PL/SQL code.
Table 22-3 ESS_JOB Functions and Procedures for Request Logging
| Method | Description |
|---|---|
|
Writes The message is logged only if the specified logging level is equal or greater than the log level specified by the Log level values correspond to those defined in Use the following values for the
|
An example of request logging by a SQL request job procedure is shown below.
create or replace procedure log_example_job
( request_handle in varchar2 )
as
v_request_id number := null;
begin
ess_job.write_log(ess_job.level_fine,
'LOG_EXAMPLE_JOB Procedure Begin');
-- Oracle Enterprise Scheduler request id being executed.
begin
v_request_id := ess_runtime.get_request_id(request_handle);
exception
when others then
ess_job.write_log(ess_job.level_severe,
'Bad request handle: '||request_handle);
raise_application_error(-20000,
'Failed to get request id for request handle '||request_handle,
true);
end;
-- Job logic
ess_job.write_log(ess_job.level_info,
'Executing job logic...');
ess_job.write_log(ess_job.level_fine,
'LOG_EXAMPLE_JOB Procedure End');
end;
/
You can write to the job request log from process job. The way this works is quite different from Java and PL/SQL jobs, where the executing code has access to an API for writing entries at a particular level. Instead, for a process job, the job's standard output and standard error are redirected to a file in the request's log work directory (a location set by Oracle Enterprise Scheduler). Oracle Enterprise Scheduler imports this file and append it to the request log in the content store.
In other words, to log from a process job, you need only write to standard output from job logic code.
The encoding used to read the log file is determined as described in Process Job Locale.
Note that you cannot log at particular levels from a process job (where the API for setting the level isn't available). So the SYS_EXT_requestLogLevel system property does not constrain log contents. Oracle Enterprise Scheduler always appends the contents of the log file to the request log in the content store.
Because an EJB Job is a Java job that gets executed remotely, the remote EJB job implementation can write content to logs and output. Use the oracle.as.scheduler.request.RemoteContentHelper API to handle this content. The following bullet items describe the high-level steps involved. Example 22-2 shows an EJB job implementation that illustrates this functionality.
Set up the RemoteContentHelper. The parameters RequestExecutionContext and RequestParameters can be obtained from the execute() method of the job implementation.
RemoteContentHelper rch=new RemoteContentHelper(RequestExecutionContext, RequestParameters);
Write content to the log file.
rch.log(Level.INFO, logMessage)
Write text output.
RuntimeServiceHandle rsh = null;
ContentHandle ch = null;
String contentName = "Content1";
String contentData = "Some text content";
try {
rsh = rch.getRuntimeService().open();
ch = rch.openOutputContent(rsh, contentName, ContentType.Text, EnumSet.of(ContentHandle.ContentOpenOptions.Write));
rchelper().write(ch, contentData);
} catch (Exception ex) {
throw new ExecutionErrorException(ex);
} finally {
rch.closeOutputContent(ch);
rch.getRuntimeService().close(rsh);
}
Write binary output.
RuntimeServiceHandle rsh = null;
ContentHandle ch = null;
String contentName = "Content1";
String contentData = "Some binary content"; //Binary content can differ in the variable declaration.
try {
rsh = rch.getRuntimeService().open();
ch = rch.openOutputContent(rsh, contentName, ContentType.Binary, EnumSet.of(ContentHandle.ContentOpenOptions.Write));
rchelper().write(ch, contentData.getBytes());
} catch (Exception ex) {
throw new ExecutionErrorException(ex);
} finally {
rch.closeOutputContent(ch);
rch.getRuntimeService().close(rsh);
}
Example 22-2 shows an EJB job implementation that demonstrates how to handle output and logs.
Example 22-2 SimpleSyncEssBean
import java.util.ArrayList;
import java.util.logging.Level;
import java.util.EnumSet;
import javax.ejb.Stateless;
import oracle.as.scheduler.RuntimeServiceHandle;
import oracle.as.scheduler.ExecutionCancelledException;
import oracle.as.scheduler.ExecutionErrorException;
import oracle.as.scheduler.ExecutionPausedException;
import oracle.as.scheduler.ExecutionWarningException;
import oracle.as.scheduler.RemoteExecutable;
import oracle.as.scheduler.RequestExecutionContext;
import oracle.as.scheduler.RequestParameters;
import oracle.as.scheduler.request.RemoteContentHelper;
import oracle.as.scheduler.request.ContentDetail;
import oracle.as.scheduler.request.ContentHandle;
import oracle.as.scheduler.request.ContentType;
@Stateless(name = "SimpleSyncEssBean")
public class SimpleSyncEssBean implements RemoteExecutable {
private RemoteContentHelper m_rch = null;
public void execute(RequestExecutionContext requestExecutionContext,
RequestParameters requestParameters) throws ExecutionErrorException, ExecutionWarningException,
ExecutionCancelledException,
ExecutionPausedException {
long requestId = requestExecutionContext.getRequestId();
// setup helper now so it is available to println
m_rch = setupRemoteContentHelper(requestExecutionContext, requestParameters);
ContentType contentType = ContentType.Text;
String contentName = requestId + "Output.txt";
ArrayList<String> srcLines = new ArrayList<String>();
srcLines.add("SimpleSyncEssBean Output Details \n");
boolean success = false;
String exmsg = "";
try {
createOutputContent(contentName, contentType, srcLines);
success = verifyOutputContent(contentName, contentType, srcLines);
} catch (ExecutionErrorException ex) {
exmsg = ex.getMessage();
}
if (!success) {
throw new ExecutionErrorException("Output test failed: " + contentName + ", " + exmsg);
} else {
printToLog("Output test succeeded: " + contentName);
}
printToLog(" SimpleSyncEssBean job succeeded. RequestId:" + requestId);
}
/**
* Creates the remote content helper for log/output.
*/
private RemoteContentHelper setupRemoteContentHelper(RequestExecutionContext ctx, RequestParameters params) throws ExecutionErrorException {
RemoteContentHelper rch = null;
try {
rch = new RemoteContentHelper(ctx, params);
} catch (Exception ex) {
throw new ExecutionErrorException(ex);
}
return rch;
}
/**
* Gets the remote content helper that is setup.
* Throws if it is not setup.
*/
private RemoteContentHelper rchelper() throws ExecutionErrorException {
if (null == m_rch) {
throw new ExecutionErrorException("RemoteContentHelper is not setup");
}
return m_rch;
}
private void printToLog(String message) throws ExecutionErrorException {
System.out.println(message);
if (m_rch != null) {
try {
m_rch.log(Level.INFO, message);
} catch (Exception ex) {
// ignore
}
} else {
rchelper();
}
}
/**
* Writes dataList as either Text or Binary output content.
*/
private void createOutputContent(String contentName, ContentType contentType,
ArrayList<String> dataList) throws ExecutionErrorException {
RuntimeServiceHandle rsh = null;
ContentHandle ch = null;
try {
rsh = rchelper().getRuntimeService().open();
ch =
rchelper().openOutputContent(rsh, contentName, contentType,
EnumSet.of(ContentHandle.ContentOpenOptions.Write));
for (String data : dataList) {
if (ContentType.Text == contentType) {
rchelper().write(ch, data);
} else {
rchelper().write(ch, data.getBytes());
}
}
} catch (Exception ex) {
throw new ExecutionErrorException(ex);
} finally {
if (ch != null) {
try {
rchelper().closeOutputContent(ch);
} catch (Exception ex) {
printToLog("Error while closing ch: " + ex.getMessage());
//ex.printStackTrace();
throw new ExecutionErrorException(ex);
}
}
if (rsh != null) {
try {
rchelper().getRuntimeService().close(rsh);
} catch (Exception ex) {
printToLog("Error while closing rsh: " + ex.getMessage());
//ex.printStackTrace();
throw new ExecutionErrorException(ex);
}
}
}
}
/**
* Verifies Text or Binary output content.
*/
private boolean verifyOutputContent(String contentName, ContentType contentType, ArrayList<String> srcDataList) throws ExecutionErrorException {
String actualData = getOutputContent(contentName, contentType);
StringBuffer sb = new StringBuffer();
for (String str : srcDataList) {
sb.append(str);
}
String srcData = sb.toString();
boolean success = srcData.equals(actualData);
if (!success) {
printToLog("Test failed for " + contentName);
printToLog("Expected data: <\n" + srcData + ">");
printToLog("Actual data: <\n" + actualData + ">");
}
try {
if (rchelper().outputContentExists(contentName)) {
ContentDetail detail = rchelper().getOutputContentDetail(contentName);
printToLog("ContentDetail:\n" + detail);
} else {
printToLog("The output content details are not present:\n");
}
} catch (Exception ex) {
String exm = "Failed to get output content detail: " + contentName;
printToLog(exm);
throw new ExecutionErrorException(ex);
}
return success;
}
/**
* Gets either Text or Binary output content as String.
*/
private String getOutputContent(String contentName, ContentType contentType) throws ExecutionErrorException {
RuntimeServiceHandle rsh = null;
long requestId = rchelper().getRequestExecutionContext().getRequestId();
ContentHandle ch = null;
String result = null;
try {
rsh = rchelper().getRuntimeService().open();
ch =
rchelper().openOutputContent(rsh, contentName, contentType,
EnumSet.of(ContentHandle.ContentOpenOptions.Read));
if (ContentType.Text == contentType) {
char[] chars = rchelper().getTextContent(ch, Integer.MAX_VALUE);
result = new String(chars);
} else {
byte[] bytes = rchelper().getBinaryContent(ch, Integer.MAX_VALUE);
result = new String(bytes);
}
} catch (Exception ex) {
throw new ExecutionErrorException(ex);
} finally {
if (ch != null) {
try {
rchelper().closeOutputContent(ch);
} catch (Exception ex) {
printToLog("Error while closing ch: " + ex.getMessage());
//ex.printStackTrace();
throw new ExecutionErrorException(ex);
}
}
if (rsh != null) {
try {
rchelper().getRuntimeService().close(rsh);
} catch (Exception ex) {
printToLog("Error while closing rsh: " + ex.getMessage());
//ex.printStackTrace();
throw new ExecutionErrorException(ex);
}
}
}
return result;
}
}
Progress messages are only available to asynchronous jobs. The Oracle Enterprise Scheduler AsyncWebServiceJob callback endpoint supports a new logAsyncWSJobProgressMessage one-way operation. This operation allows an asynchronous SOA composite (or other asynchronous web service) to log progress messages using ws-addressing for correlation and the same callback endpoint and associated callback OWSM policy. This provides a simple, convenient option for logging progress messages from asynchronous SOA composites.
The Oracle Enterprise Scheduler asynchronous web service job callback endpoint WSDL provides the necessary information for using this operation. A portion of the WSDL is shown in Example 22-3.
Example 22-3 Asynchronous Web Service Job Callback Endpoint WSDL
<xsd:complexType name="logAsyncWSJobProgressMessage">
<xsd:sequence>
<xsd:element name="level" type="tns:logLevel" form="qualified"/>
<xsd:element name="message" type="xsd:string" form="qualified"/>
</xsd:sequence>
</xsd:complexType>
<xsd:element name="logAsyncWSJobProgressMessage" type="tns:logAsyncWSJobProgressMessage"/>
<message name="logAsyncWSJobProgressMessageInput">
<part name="parameters" element="tns:logAsyncWSJobProgressMessage"/>
</message>
<portType name="RequestPort">
<operation name="logAsyncWSJobProgressMessage">
<input message="tns:logAsyncWSJobProgressMessageInput" xmlns:ns1="http://www.w3.org/2006/05/addressing/wsdl" ns1:Action="logAsyncWSJobProgressMessage"/>
</operation>
</portType>
You can use methods of the oracle.as.scheduler.RuntimeService class to handle logs stored in the Oracle Enterprise Scheduler content store. You'll need to first get a RuntimeServiceHandle instance. You'll pass this instance as an argument for each of these RuntimeService methods.
For more on the RuntimeServiceHandle, see How to Access the Runtime Service and Obtain a Runtime Service Handle.
Table 22-4 RuntimeService Methods for Handling Request Logs
| Method | Description |
|---|---|
|
Returns a |
|
Returns a |
|
Returns a String array with at most |
|
Returns a char array with at most |
|
Closes the previously opened log or output content and releases the handle. |
You can have your job create output content at runtime. For example, your job might collect data that would be useful in a report for users. When you generate output at runtime, it's available to be retrieved later through a client user interface or the Fusion Middleware Control.
The output your code creates can be created directly in the Oracle Enterprise Scheduler content store, or it can be created in the file system and imported to the content store. Oracle Enterprise Scheduler can import it automatically or your job can use Oracle Enterprise Scheduler APIs to import it explicitly.
When you use the file system, you write to a particular directory whose location has been configured in the Oracle Enterprise Scheduler ess-config.xml file. Oracle Enterprise Scheduler creates a request file directory to contain files written from all requests. Your code writes to a subdirectory of this created specifically for the request. Oracle Enterprise Scheduler automatically imports all of the request's output to the content store, and then deletes request-specific subdirectories.
Oracle Enterprise Scheduler provides APIs for managing output content in the content store.
The request file directory is specified in the Oracle Enterprise Scheduler ess-config.xml file. For each request, Oracle Enterprise Scheduler can create request-specific subdirectories of this request file directory: a working directory for temporary files and an output directory for output files that should be imported into the content store.
Your code can write temporary and output files to their respective request-specific directories at runtime. Oracle Enterprise Scheduler imports to the content store files in the request's output directory. When the content is imported depends on whether the request file directory is shared or local, as described in Common Request File Directory Behavior, Shared Request File Directory Behavior, and Local Request File Directory Behavior.
After automatically importing all of the request's output to the content store, Oracle Enterprise Scheduler deletes the request-specific output directory and its contents.
The request file directory can be local, meaning that it is used only for work done on a single server. It can also instead be shared, in which a single directory is used for work done on multiple servers. Runtime behavior differs depending on whether the directory is configured to be local or shared.
The directory is specified in the ess-config.xml file, as shown in Example 22-4. Oracle Enterprise Scheduler sets USER_FILE_DIR (SYS_userFileDir) based on RequestFileDirectory and then makes the property read-only. The job cannot override this by setting USER_FILE_DIR.
Example 22-4 Request File Directory Configuration with ess-config.xml file
<ess:EssConfig xmlns:ess="http://ess.oracle.com"
xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<ess:EssProperties>
<ess:EssProperty key="RequestFileDirectory" value="/etc/outputfiles"
immutable="true"/>
<ess:EssProperty key="RequestFileDirectoryShared" value="false"
immutable="true"/>
</ess:EssProperties>
</ess:EssConfig>
Oracle Enterprise Scheduler automatically imports all request output files from the output directory to the content store, and deletes the request working directory and all files in it.
Imported files always overwrite existing content of the same file name as long as the existing content was previously imported. If the existing content was created using the API, then it is considered to be distinct from the new file, and the new file does not overwrite and is ignored. In other words, content created with the API has precedence.
Oracle Enterprise Scheduler does not import output files of zero length.
Any files created by the request remains in its working and output directories until the request completes and goes to a terminal state. Any files created by a request in a shared file directory are available to all stages of the request.
Oracle Enterprise Scheduler creates the request work directory before the job request transitions to the RUNNING state. Any error while creating the directory results in a system error for the request.
For process a job, importing the log occurs after the request transitions to a terminal state. If an error occurs while importing the log, the error is logged and the request log is left in the file system. You must manually import the log to the content store.
Importing output files for any job type occurs after the request transitions to a terminal state. If there is an error while importing output files, the error is logged and the output files are left in their directories on the file system. You must remove the output files.
Oracle Enterprise Scheduler creates request-specific directories before any stage of the request runs. If the request file directory is local, it must be a location that is guaranteed to exist locally on every server. In this case, files created by one stage of the request are not guaranteed to be available in the next stage because stages are independent units of work and may run on different servers.
For a local request file directory, the common behavior holds except that Oracle Enterprise Scheduler performs the actions for each stage. The reason is that each stage may execute on a different server, and it is necessary for Oracle Enterprise Scheduler to capture and clean up the files for each stage because they may not be there for the next stage.
In case a request requires access to all previously imported output files, it can set the parameter SYS_EXT_executeAutoExport = true. If this is set, at the beginning of the execute stage, Oracle Enterprise Scheduler automatically exports previously imported output files to the request's working output directory. This gives you an opportunity to update the file before it is imported back to the content store at the end of the execute stage. (Note that the content isn't removed from the content store when the content is exported.) Furthermore, Oracle Enterprise Scheduler provides an API for a request to selectively export previously imported output files.
When a local request file directory is used, file imports happen at the end of each stage (pre-processing, execution, update, post-processing). If an error occurs while importing logs or output files, the log and output files that failed to import are moved to a mirror directory at request_file_directory/preserve. For example, for request 18 this would be request_file_directory/preserve/18.
For the pre-processing stage, an error creating the request directory at the beginning of the stage or importing output files at the end of the stage results in a system error for the request.
For the post-processing stage, an error creating the request directory at the beginning of the stage or importing output files at the end of the stage results in a warning for the request.
For the execution stage of a Java job, asynchronous Java job, and process job request, an error creating the request directory or automatically exporting previously imported output files (such as when the SYS_EXT_executeAutoExport system property is used) at the beginning of the stage or importing output files at the end of the stage results in a system error for the request.
If the request is a process job, an error importing the request log is logged and not treated as an error. The log is left in the file system, and you may manually import it to the content store. If there is an internal error during execution of a process job, log and output files are not imported because the job could still be running. The log and output files are imported when the job is terminated, either automatically or manually by the user. If the job goes to ERROR_MANUAL_RECOVERY, it is the user's responsibility to clean up the request log and output files.
For the update stage, an error creating the request directory or importing output files is logged only.
Setting the SYS_EXT_supportOutputFiles system property is essential to using the request file directory and automatic importing of output files.
To use the request output directory to create output files, the job must define a parameter using the system property SYS_EXT_supportOutputFiles. Depending on what sort of files the job wants to create, the property can be set in one of the following ways:
Set it to "output" in order to have files written to the request output directory imported to the content store.
Set it to "work" in order to write files to the request working directory that are not intended for import, such as temporary files.
Set it to "none", or leave it undefined, if the job does not create any output or temporary files.
Table 22-5 System Properties for Creating Request Output
| Method | Description |
|---|---|
|
String property indicating whether a job creates files in the file system. Supported values are |
|
Boolean property indicating whether previously imported output files shall be exported at the start of the execute stage. The content isn't removed from the content store when it is automatically exported. |
To create request output from Java, your job's code can use the Oracle Enterprise Scheduler API to create output content directly in the content store, or your job can create files in the request's output directory in the file system. If your job creates files in the request's output directory, you can either explicitly import those files to the content store or allow Oracle Enterprise Scheduler to automatically import the files to the content store.
Using the API, the job can create text or binary output content. Imported output files are always imported as binary content, meaning the bytes are uninterpreted.
The Java APIs available for handling request output include the following:
Use the ContentFactory class to get instances of other classes you can use to create and manage output content, including RequestOutput and OutputContentHelper output. See Table 22-6.
Use the RequestOutput class to create output content directly in the content store. See Table 22-7.
Use the OutputContentHelper class to explicitly manage content you create as files in the request output file directory, and to interact with the content store. See Table 22-8.
The oracle.as.scheduler.request.ContentFactory class provides methods to get your code access to the output content framework, as well as to an instance you can use to create the output itself.
Table 22-6 ContentFactory Methods for Java Request Output
| Method | Description |
|---|---|
|
Returns a |
|
Returns a |
|
Returns a |
The oracle.as.scheduler.request.RequestOutput class represents the output your code is creating. You get an instance of this class from ContentFactory.getRequestOutput, then use its write methods to write to the output content you are creating.
Table 22-7 RequestOutput Methods for Java Request Output
| Method | Description |
|---|---|
|
Appends |
|
Appends |
|
Appends |
|
Appends |
|
Appends chars to the text output content. |
|
Appends bytes to the binary output content. |
|
Appends bytes to the binary output content. |
Methods of the oracle.as.scheduler.request.OutputContentHelper class do the heavy lifting for output file handling in Java jobs. Using these methods, your code can work with the request file directory and the content store itself.
Note that methods for importing content to the content store take a OutputContentHelper.CommitSemantics enum instance that you can use to specify transaction semantics during import. For more information, see Table 22-9.
Table 22-8 OutputContentHelper Methods for Java Request Output
| Method | Description |
|---|---|
|
Returns The job must define the |
|
Returns The job must define the |
|
Returns |
|
Returns a String with the request work directory as resolved to the current server. The job may create temporary files in the work directory, and Oracle Enterprise Scheduler automatically deletes the work directory at the end of request execution if the |
|
Returns a String with the request output directory, resolved to the current server. The job may create output files in the output directory that can be automatically or manually imported to the Oracle Enterprise Scheduler content store. |
|
Returns an |
|
Returns an |
|
Returns an |
|
Returns an |
|
Returns a list of |
|
Returns a |
|
Returns |
|
Deletes the specified output content from the content store for the request. Can delete output content that was imported and output content created using the API. |
Use the oracle.as.scheduler.request.OutputContentHelper.CommitSemantics enum to specify what should happen if errors occur while importing content to the content store.
Table 22-9 CommitSemantics Enum Members to Express Commit Semantics
| Field | Description |
|---|---|
|
Stop the operation for all files when there is an error on a file. If the handle is internal, it is committed. |
|
Attempt the operation on all files regardless of errors. If the handle is internal, it is committed. |
|
Stop the operation for all files when any file has an error. This is not valid with a user-provided handle. |
Example 22-5 illustrates how to create output content using the RequestOutput API. The output content is created directly in the content store.
Example 22-6 illustrates how to create an output file in the request output directory. Remember that the job must define the SYS_EXT_supportOutputFiles system property as output. This example is appropriate for a Java job, an asynchronous Java job, a pre-processor, or a post-processor.
The following example shows how to manually export and import output files. This would be useful if you need to create content from files during update. Be aware that you can export only files that have been imported and not files that were created using the API.
The example illustrates the scenario that a file that may have been created previously must be updated and imported.
import oracle.as.scheduler.request.ContentFactory;
import oracle.as.scheduler.request.ImportExportResult;
import oracle.as.scheduler.request.ImportExportResult.ImportExportStatus;
import oracle.as.scheduler.request.OutputContentHelper;
import oracle.as.scheduler.request.OutputContentHelper.CommitSemantics;
class ExampleExportImport{
OutputContentHelper helper = ContentFactory.getOutputContentHelper(requestId);
if (!helper.outputDirectoryExists())
{
// error - make sure job definition defines SYS_EXT_supportOutputFiles
}
String outputDir = helper.getResolvedOutputDirectory();
String fileName = "myfile.out";
List<String> fileNamesList = new ArrayList<String>();
fileNamesList.add(fileName);
// Export the file if it exists; otherwise, create it.
if (helper.outputContentExists(fileName))
{
ImportExportResult exportResult = helper.exportOutputContent(fileNamesList);
if (exportResult.getStatus() != ImportExportStatus.Success)
{
// handle error
}
}
else
{
File f = new File(outputDir, fileName);
f.createNewFile();
}
// ... update the file as needed ...
// Import the new or updated file.
// Updated file overwrites previous contents.
ImportExportResult importResult =
helper.importOutputFile(fileNamesList, CommitSemantics.IgnoreErrors);
if (importResult.getStatus() != ImportExportStatus.Success)
{
// handle error
}
}
Example 22-5 Creating Output Content using RequestOutput
import oracle.as.scheduler.request.ContentFactory;
import oracle.as.scheduler.request.ContentType;
import oracle.as.scheduler.request.RequestOutput;
class ExampleOutputContentCreator
{
RuntimeService runtimeService = getRuntimeService();
RuntimeServiceHandle handle;
try {
handle = runtimeService.open();
RequestOutput requestOutput = ContentFactory.getRequestOutput(
handle, requestId, ContentType.Text, “SampleOutput.txt");
requestOutput.writeln(“Output data in sample output content.");
}
finally {
runtimeService.close(handle);
}
}
Example 22-6 Creating an Output File for Automatic Import
import oracle.as.scheduler.request.ContentFactory;
import oracle.as.scheduler.request.OutputContentHelper;
class ExampleOutputCreator{
OutputContentHelper helper = ContentFactory.getOutputContentHelper(requestId);
String outputDir = helper.getResolvedOutputDirectory();
File f = new File(outputDir, "myfile");
f.createNewFile();
if (f.exists())
{
// write to file
}
}
To create request output from PL/SQL, your code can use the ESS_JOB PL/SQL package to create output content directly in the content store.
Using functions and procedures in the package, the job can create text or binary output content.
Table 22-10 ESS_JOB Procedures and Functions for Request Output
| Method | Description |
|---|---|
|
Returns a handle from opening the specified output content for the request associated with the current session. These are convenience functions that call |
|
Returns an opaque handle from opening the output content This creates a new output content entry if one does not already exist for the given name. If one already exists, then the specified content type must match that already established for that name.
This returns an opaque handle that is passed to subsequent procedures that operate on that output content. The content entry is locked on successful return from this function. It may or may not be locked if this procedure fails. A commit or rollback releases the lock. The You should call close_content to free any resources associated with the handle returned by this method. The close should be done prior to transaction commit or rollback. NOTE: The content output support has DML semantics. The caller is responsible for the commit/rollback. |
|
Writes data as
NOTE: The content output support has DML semantics. The caller is responsible for the commit/rollback. |
|
Writes binary data as
NOTE: The content output support has DML semantics. The caller is responsible for the commit/rollback. |
|
Closes the output content handle. This releases resources associated with the given handle and it is no longer valid. Call this method before transaction commit or rollback. p_content_handle is the output handle from a prior NOTE: The content output support has DML semantics. The caller is responsible for the commit/rollback. This method does not automatically perform a commit or rollback |
|
Returns true if an output content entry having the specified name already exists for the request associated with the current session.
|
|
Deletes the specified output content entry for the request associated with the current session.
|
Example 22-7 illustrates how to write text content into output, as well as how to write log entries along the way.
Example 22-8 illustrates how to write binary content for output.
Example 22-7 PL/SQL Output Creation Examples
create or replace procedure text_output_example_job
( request_handle in varchar2 )
as
v_request_id number := null;
v_content_name varchar2(100) := 'mycontent.txt';
v_content_handle varchar2(100);
v_ntext nvarchar2(100);
begin
ess_job.write_log(ess_job.LEVEL_FINE,
'TEXT_OUTPUT_EXAMPLE_JOB Procedure Begin');
-- Oracle Enterprise Scheduler request id being executed.
begin
v_request_id := ess_runtime.get_request_id(request_handle);
exception
when others then
ess_job.write_log(ess_job.LEVEL_SEVERE,
'Bad request handle: '||request_handle);
raise_application_error(-20000,
'Failed to get request id for request handle '||request_handle,
true);
end;
begin
-- ----------
-- Delete content entry if it already exists.
-- ----------
if (not ess_job.output_content_exists(v_content_name)) then
ess_job.write_log(ess_job.LEVEL_FINEST,
'Content does not exist: ' || v_content_name);
else
ess_job.write_log(ess_job.LEVEL_INFO,
'Deleting existing content: ' || v_content_name);
ess_job.delete_output_content(v_content_name);
commit;
end if;
-- ----------
-- Write text content. Source data has some non-ascii chars.
-- Illustrate multiple writes.
-- ----------
ess_job.write_log(ess_job.LEVEL_FINE,
'Write text content: '||v_content_name);
v_content_handle := null;
v_content_handle := ess_job.open_text_output_content(v_content_name);
ess_job.write_text_content(v_content_handle,
'Data ');
ess_job.write_ntext_content(v_content_handle,
unistr('(NTEXT data:\00c4\00c5)'));
ess_job.write_text_content(v_content_handle,
' for CONTENT ' || v_content_name);
ess_job.close_content(v_content_handle);
v_content_handle := null;
commit;
exception
when others then
ess_job.write_log(ess_job.LEVEL_WARNING,
'Error during text output operations. ' ||
'content: ' || v_content_name || chr(10) ||
'Error_Stack...' || chr(10) ||
dbms_utility.format_error_stack() || chr(10) ||
'Error_Backtace...' || chr(10) ||
dbms_utility.format_error_backtrace());
if v_content_handle is not null then
ess_job.close_content(v_content_handle);
v_content_handle := null;
end if;
rollback;
raise_application_error(-20000,
'Output content operations failed for '||v_content_name);
end;
ess_job.write_log(ess_job.level_info,
'TEXT_OUTPUT_EXAMPLE_JOB Procedure End');
end;
/
Example 22-8 Manual Export and Import of Request Output
create or replace procedure binary_output_example_job
( request_handle in varchar2 )
as
v_request_id number := null;
v_content_name varchar2(100) := 'mycontent.bin';
v_content_handle varchar2(100);
v_nchar_cs varchar2(100);
v_dest_cs varchar2(100);
v_ntext nvarchar2(100);
v_raw raw(500);
begin
ess_job.write_log(ess_job.LEVEL_FINE,
'BINARY_OUTPUT_EXAMPLE_JOB Procedure Begin');
-- Oracle Enterprise Scheduler request id being executed.
begin
v_request_id := ess_runtime.get_request_id(request_handle);
exception
when others then
ess_job.write_log(ess_job.LEVEL_SEVERE,
'Bad request handle: '||request_handle);
raise_application_error(-20000,
'Failed to get request id for request handle '||request_handle,
true);
end;
begin
-- ----------
-- Delete content entry if it already exists.
-- ----------
if (not ess_job.output_content_exists(v_content_name)) then
ess_job.write_log(ess_job.LEVEL_FINEST,
'Content does not exist: ' || v_content_name);
else
ess_job.write_log(ess_job.LEVEL_INFO,
'Deleting existing content: ' || v_content_name);
ess_job.delete_output_content(v_content_name);
commit;
end if;
-- ----------
-- Write binary content.
-- This is the UTF-8 representation of a string for a known byte
-- encoding rather than whatever the charset/national charset
-- happens to be for this database.
-- Source data has couple non-ascii chars.
-- ----------
-- database national character set being used
select value into v_nchar_cs
from nls_database_parameters
where parameter = 'NLS_NCHAR_CHARACTERSET';
ess_job.write_log(ess_job.LEVEL_FINEST,
'NLS_NCHAR_CHARACTERSET = '||v_nchar_cs);
ess_job.write_log(ess_job.LEVEL_FINE,
'Write binary content: '||v_content_name);
v_content_handle := null;
v_content_handle := ess_job.open_binary_output_content(v_content_name);
v_ntext := unistr('Data (NTEXT data:\00c4\00c5) for CONTENT ' ||
v_content_name);
v_dest_cs := 'AL32UTF8';
v_raw := utl_raw.cast_to_raw(convert(v_ntext, v_dest_cs, v_nchar_cs));
ess_job.write_binary_content(v_content_handle, v_raw);
ess_job.write_log(ess_job.LEVEL_FINE,
'Wrote '||utl_raw.length(v_raw)||' bytes' ||
' using ' || v_dest_cs || ' charset');
ess_job.close_content(v_content_handle);
v_content_handle := null;
commit;
exception
when others then
ess_job.write_log(ess_job.LEVEL_WARNING,
'Error during binary output operations. ' ||
'content_name=' || v_content_name || chr(10) ||
'Error_Stack...' || chr(10) ||
dbms_utility.format_error_stack());
if v_content_handle is not null then
ess_job.close_content(v_content_handle);
v_content_handle := null;
end if;
rollback;
raise_application_error(-20000,
'Output content operations failed for '||v_content_name);
end;
ess_job.write_log(ess_job.level_info,
'BINARY_OUTPUT_EXAMPLE_JOB Procedure End');
end;
/
You create output from process job logic by writing the content to the location specified by the ESS_OUTPUT_WORK_DIR environment variable that is available for all process jobs. As with other jobs, ensure that the SYS_EXT_supportOutputFiles system property is set to output so that the environment variable is defined for the job.
After your process code writes the file, Oracle Enterprise Scheduler automatically imports output files in the directory into the content store as binary content.
See Request Logging and Output From an EJB Job for a description and examples about how to create output from an EJB job.
For synchronous and asynchronous web services, request output content is automatically created from the response message payload as described below. The output content is text data with the name WebServiceJobOutput-REQUESTID.txt, where REQUESTID is the request ID of the request.
For a synchronous web service, the response message payload is captured as the request output.
For an asynchronous web service, the callback/response message payload received at EssWsJobAsyncCallbackService is captured as the request output when the job status is SUCCESS.
You can use methods of the oracle.as.scheduler.RuntimeService class to handle request output stored in the Oracle Enterprise Scheduler content store. You'll need to first get a RuntimeServiceHandle instance. You'll pass this instance as an argument for each of these RuntimeService methods. For more on the RuntimeServiceHandle, see How to Access the Runtime Service and Obtain a Runtime Service Handle.
Table 22-11 RuntimeService Methods for Handling Request Output
| Method | Description |
|---|---|
|
Returns a |
|
Returns a |
|
Opens the specified request output to retrieve output data for the specified content, returning |
|
Returns a |
|
Returns a byte array with at most |
|
Closes the previously opened log or output content and releases the handle. |