com.ibm.optim.oaas.client.job

Interface JobRequestBuilder

public interface JobRequestBuilder

Builder to configure a job request.

Method Summary

Methods

Modifier and Type	Method and Description
JobRequestBuilder	application(String applicationId) Sets the application ID.
JobRequest	build() Returns the configured job request.
JobRequestBuilder	clientEmail(String email) Sets the client email address.
JobRequestBuilder	clientName(String name) Sets the client name used to identify the client submitting a job.
JobRequestBuilder	copy(String jobId) Indicates that the new job should be constructed by copying an existing job.
JobRequestBuilder	copy(String jobId, boolean shallow) Indicates that the new job should be constructed by copying an existing job.
Future<JobResponse>	create(JobExecutor executor) Builds the request and creates the job using a given job executor.
JobRequestBuilder	deleteOnCompletion(boolean delete) Indicates that the job must be deleted on completion.
Future<JobResponse>	execute(JobExecutor executor) Builds the request and executes it using a given job executor
JobRequestBuilder	input(File file) Sets an input source to the given file.
JobRequestBuilder	input(JobInput input) Adds a custom job input source.
JobRequestBuilder	input(String name, File file) Sets an input source to the given file with a specific name.
JobRequestBuilder	input(String name, InputStream stream) Sets an input source to the given stream.
JobRequestBuilder	input(String name, com.fasterxml.jackson.databind.ObjectMapper mapper, Object input) Sets the input to the given JSON document.
JobRequestBuilder	input(String name, URL url) Sets an input source to the given URL with a specific name.
JobRequestBuilder	livelog(OutputStream stream) Sets the live log output to a stream.
JobRequestBuilder	livelog(OutputStream stream, com.ibm.icu.text.DateFormat format) Sets the live log output to a stream.
JobRequestBuilder	log(File file) Sets the log output to a file.
JobRequestBuilder	log(OutputStream stream) Sets the log output to a stream.
JobRequestBuilder	output(File file) Sets the result output to a file.
JobRequestBuilder	output(JobOutput output) Adds a custom result output.
<T> JobRequestBuilder	output(com.fasterxml.jackson.databind.ObjectMapper mapper, Class<T> type) Sets the result output to a JSON object.
<T> JobRequestBuilder	output(com.fasterxml.jackson.databind.ObjectMapper mapper, com.fasterxml.jackson.core.type.TypeReference<T> type) Sets the result output to a JSON object.
JobRequestBuilder	output(OutputStream stream) Sets the result output to a stream.
JobRequestBuilder	output(String attid, File file) Sets the result output to a file for a particular output attachment.
<T> JobRequestBuilder	output(String attid, com.fasterxml.jackson.databind.ObjectMapper mapper, Class<T> type) Sets the result output to a JSON object for a particular output attachment.
<T> JobRequestBuilder	output(String attid, com.fasterxml.jackson.databind.ObjectMapper mapper, com.fasterxml.jackson.core.type.TypeReference<T> type) Sets the result output to a JSON object for a particular output attachment.
JobRequestBuilder	output(String attid, OutputStream stream) Sets the result output to a stream for a particular output attachment.
JobRequestBuilder	parameter(String name, Object value) Sets the value of a parameter.
JobRequestBuilder	recreate(String jobId) Indicates that the new job should be constructed by replacing an existing job.
JobRequestBuilder	timeout(long timeout, TimeUnit unit) Sets the timeout for the job monitoring.
JobRequestBuilder	useBatchSubmitMode() Tries to create a job, upload attachments, and submit a job in one call to avoid network round trips.
JobRequestBuilder	version(String version) Sets the application version to use during solve.

Method Detail

application

JobRequestBuilder application(String applicationId)

Sets the application ID. The application ID refers to the type of engine (for example opl or cplex). There are two ways to manage the application ID:

• The application ID can be specified explicitly at creation time. In this case, the attachments can be declared and uploaded incrementally. When the job is submitted, the list of attachments must be compatible with the application ID, otherwise an exception will be returned.
• The application ID can be left unspecified at creation time. In this case, the full list of attachments must be declared, and the application ID will be deduced from the attachment extensions.

Parameters:

applicationId - The application ID.

Returns:

The builder.

version

JobRequestBuilder version(String version)

Sets the application version to use during solve. If this version is not available a JobFailureType.PROCESSING failure is raised. If nothing is specified latest version is used. It is possible for a solved job to get version used during solve using Job.getApplicationVersionUsed()

Parameters:

version - The application version.

Returns:

The builder.

clientName

JobRequestBuilder clientName(String name)

Sets the client name used to identify the client submitting a job. The client name may be used to distinguish between different clients using the same subscription.

Parameters:

name - The client name.

Returns:

The builder.

clientEmail

JobRequestBuilder clientEmail(String email)

Sets the client email address. The email address is used for notification of job completion as well as alerts.

Parameters:

email - The client email address.

Returns:

The builder.

parameter

JobRequestBuilder parameter(String name,
                          Object value)

Sets the value of a parameter.

Parameters:

name - The parameter name.

value - The parameter value.

Returns:

The builder.

input

JobRequestBuilder input(File file)

Sets an input source to the given file. Several input sources can be defined.

Parameters:

file - The file.

Returns:

The builder.

useBatchSubmitMode

JobRequestBuilder useBatchSubmitMode()

Tries to create a job, upload attachments, and submit a job in one call to avoid network round trips. This optimized mode may not work if attachments are too big or if infrastructure does not support multipart messages. Auto retry is not available in this mode. Only File and InputStream attachments are supported in batch mode.

Returns:

The builder.

input

JobRequestBuilder input(String name,
                      File file)

Sets an input source to the given file with a specific name. The name must be a file name with an extension valid for this job. Several input sources can be defined.

Parameters:

name - The attachment name.

file - The file.

Returns:

The builder.

input

JobRequestBuilder input(String name,
                      URL url)

Sets an input source to the given URL with a specific name. The name must be a file name with an extension valid for this job. Several input sources can be defined.

Parameters:

name - The attachment name.

url - The URL.

Returns:

The builder.

input

JobRequestBuilder input(String name,
                      InputStream stream)

Sets an input source to the given stream. The name must be a file name with an extension valid for this job. Several input sources can be defined.

Parameters:

name - The attachment name.

stream - The stream.

Returns:

The builder.

input

JobRequestBuilder input(String name,
                      com.fasterxml.jackson.databind.ObjectMapper mapper,
                      Object input)

Sets the input to the given JSON document. The name must be a file name with an extension valid for this job. Several input sources can be defined.

Parameters:

name - The attachment name.

mapper - The mapper used to serialize the object.

input - The input object.

Returns:

The builder.

input

JobRequestBuilder input(JobInput input)

Adds a custom job input source. The name of the input source will be used to declare the attachment, and when the executor is ready to upload the content, it delegates it to the job input.

Parameters:

input - The custom job input.

Returns:

The builder.

output

JobRequestBuilder output(File file)

Sets the result output to a file. Single output attachment is processed by this call. For multiple result attachments use output(String, File) or JobClient.downloadJobAttachment(String, String). Several output commands can be combined in the same request.

Parameters:

file - The file to write to.

Returns:

The builder.

output

JobRequestBuilder output(OutputStream stream)

Sets the result output to a stream. Single output attachment is processed by this call. For multiple result attachments use output(String, OutputStream) or JobClient.downloadJobAttachment(String, String). Several output commands can be combined in the same request.

Parameters:

stream - The stream to write to.

Returns:

The builder.

output

JobRequestBuilder output(JobOutput output)

Adds a custom result output. When the executor is ready to get the output attachment, it sets the name of the job output and it delegates the upload to it. Several output commands can be combined in the same request.

Parameters:

output - The custom output.

Returns:

The builder.

output

<T> JobRequestBuilder output(com.fasterxml.jackson.databind.ObjectMapper mapper,
                           com.fasterxml.jackson.core.type.TypeReference<T> type)

Sets the result output to a JSON object. Single output attachment is processed by this call. For multiple result attachments use output(String, ObjectMapper, TypeReference) or JobClient.downloadJobAttachment(String, String). Several output commands can be combined in the same request.

Type Parameters:

T - The object type.

Parameters:

mapper - The JSON mapper.

type - The class of the object type.

Returns:

The builder.

output

<T> JobRequestBuilder output(com.fasterxml.jackson.databind.ObjectMapper mapper,
                           Class<T> type)

Sets the result output to a JSON object. Single output attachment is processed by this call. For multiple result attachments use output(String, ObjectMapper, Class) or JobClient.downloadJobAttachment(String, String). Several output commands can be combined in the same request.

Type Parameters:

T - The object type.

Parameters:

mapper - The JSON mapper.

type - The class of the object type.

Returns:

The builder.

log

JobRequestBuilder log(File file)

Sets the log output to a file. The log is retrieved at the end of the job execution and copied into the given file. Several log commands can be combined in the same request.

Parameters:

file - The file to write to.

Returns:

The builder.

log

JobRequestBuilder log(OutputStream stream)

Sets the log output to a stream. The log is retrieved at the end of the job execution and copied into the given stream. Several log commands can be combined in the same request.

Parameters:

stream - The stream to write to.

Returns:

The builder.

livelog

JobRequestBuilder livelog(OutputStream stream)

Sets the live log output to a stream. The live log is updated incrementally while the job is running. Only one output stream can be defined for a request.

Parameters:

stream - The stream to write to.

Returns:

The builder.

livelog

JobRequestBuilder livelog(OutputStream stream,
                        com.ibm.icu.text.DateFormat format)

Sets the live log output to a stream. The live log is updated incrementally while the job is running. Only one output stream can be defined for a request.

Parameters:

stream - The stream to write to.

format - Date formatter for the dates in the log.

Returns:

The builder.

deleteOnCompletion

JobRequestBuilder deleteOnCompletion(boolean delete)

Indicates that the job must be deleted on completion. A job is completed if its status is one of PROCESSED, FAILED, or INTERRUPTED.

Parameters:

delete - true if it must be deleted, false otherwise.

Returns:

The builder.

timeout

JobRequestBuilder timeout(long timeout,
                        TimeUnit unit)

Sets the timeout for the job monitoring. If the timeout value is reached, an interrupted exception will be thrown. By default, the timeout defined in the executor is used. The timeout only stops the monitoring, and jobs may still be running. To limit the job execution time, refer to JobParameters.TIME_LIMIT parameter.

Parameters:

timeout - The timeout: -1 for no timeout or 0 for the executor default timeout.

unit - The time unit.

Returns:

The builder.

build

JobRequest build()

Returns the configured job request.

Returns:

The job request.

execute

Future<JobResponse> execute(JobExecutor executor)
                            throws OperationException,
                                   IOException,
                                   InterruptedException,
                                   JobException

Builds the request and executes it using a given job executor

Parameters:

executor - The job executor.

Returns:

The future of the job response.

Throws:

OperationException - if any other remote exception was raised.

IOException - if an I-O exception was raised.

InterruptedException - if the job was interrupted.

JobException - if the job failed.

See Also:

JobExecutor.execute(JobRequest)

create

Future<JobResponse> create(JobExecutor executor)
                           throws OperationException,
                                  IOException,
                                  InterruptedException,
                                  JobException

Builds the request and creates the job using a given job executor.

Parameters:

executor - The job executor.

Returns:

The future of the job response.

Throws:

OperationException - if any other remote exception was raised.

IOException - if an I-O exception was raised.

InterruptedException - if the job was interrupted.

JobException - if the job failed.

See Also:

JobExecutor.create(JobRequest, JobCallback)

copy

JobRequestBuilder copy(String jobId)

Indicates that the new job should be constructed by copying an existing job. Parameters and input attachments are automatically copied to the new job from the existing job. The builder can be used to override parameters and define additional input attachments.

Parameters:

jobId - The ID of the job to copy.

Returns:

The builder.

copy

JobRequestBuilder copy(String jobId,
                     boolean shallow)

Indicates that the new job should be constructed by copying an existing job. Parameters and input attachments are automatically copied to the new job from the existing job. The builder can be used to override parameters and define additional input attachments.

Parameters:

jobId - The ID of the job to copy.

shallow - true if a shallow copy is requested.

Returns:

The builder.

recreate

JobRequestBuilder recreate(String jobId)

Indicates that the new job should be constructed by replacing an existing job. Parameters and input attachments are automatically imported in the created job. The builder can be used to override parameters and define additional input attachments.

Parameters:

jobId - The ID of the job to replace.

Returns:

The builder.

output

JobRequestBuilder output(String attid,
                       File file)

Sets the result output to a file for a particular output attachment. Several output commands can be combined in the same request.

Parameters:

attid - The output attachment ID.

file - The file to write to.

Returns:

The builder.

output

<T> JobRequestBuilder output(String attid,
                           com.fasterxml.jackson.databind.ObjectMapper mapper,
                           Class<T> type)

Sets the result output to a JSON object for a particular output attachment. Several output commands can be combined in the same request.

Type Parameters:

T - The output type.

Parameters:

attid - The output attachment ID.

mapper - The JSON mapper.

type - The class of the output type.

Returns:

The builder.

output

<T> JobRequestBuilder output(String attid,
                           com.fasterxml.jackson.databind.ObjectMapper mapper,
                           com.fasterxml.jackson.core.type.TypeReference<T> type)

Sets the result output to a JSON object for a particular output attachment. Several output commands can be combined in the same request.

Type Parameters:

T - The output type.

Parameters:

attid - The output attachment ID.

mapper - The JSON mapper.

type - The type reference of the output type.

Returns:

The builder.

output

JobRequestBuilder output(String attid,
                       OutputStream stream)

Sets the result output to a stream for a particular output attachment. Several output commands can be combined in the same request.

Parameters:

attid - The output attachment ID.

stream - The stream to write to.

Returns:

The builder.