The Oracle I/PM API's ApplicationService and DocumentService interfaces are used to manage applications and documents in the imaging system. All documents must be associated with an imaging application. The application defines many default features that are then applied to the documents that are associated with the application. In this way, an application may be thought of as a template that defines a single document type. Typically, a single application is created for documents of a single type (for example, invoices, proposals, contracts, and so on).
This chapter details how to use basic methods used for creating documents in an application including mechanisms for list and getting existing application definitions and mechanisms for uploading and indexing documents.
The following sections are included in this chapter:
The Oracle I/PM API provides two mechanisms for enumerating the list of applications defined within and I/PM system: ApplicationService.listApplications and DocumentService.listTargetApplications. Each operation accepts an “Ability” parameter that specifies which applications to return based the user's security settings. However, they differ in one which security filter is used.
The ApplicationService.listApplications returns applications based on Application definition security. Ability.VIEW returns all applications to which the calling user has view permission. The Ability.MANAGE parameter returns all applications to which that user has either delete or modify permissions. The intended purpose of this operation is primarily for code written to manage application definitions.
The DocumentService.listTargetApplications returns applications based on the user's document permissions within the application, i.e., whether the user has either view document or create document permissions for that application. This operation is the best choice when the client is working with directly documents.
Both of these operations return a java.util.List of NameId objects identifying both the numerical ID and the textual name for the application.
As with list applications, the Oracle I/IPM API provides two distinct operations for getting details of the field defined for an application: ApplicationService.getApplication and DocumentService.getTargetApplication. These operations again differ by the permissions used to determine whether or not the user is allowed to get the requested application. ApplicationService.getApplication requires application view permissions. DocumentService.getTargetApplication requires document view permissions.
Application.getApplication operation is intended for use when managing the definition itself and provides a parameter for specifying which sections of the definition are desired. Sections are requested using a SectionSet, which is a container for passing in a list of SectionFlags. For example, in order to get the application's properties and field definitions sections, calling code would pass in a SectionSet defined as follows:
sectionSet =
Application.SectionSet.of(Application.SectionFlag.PROPERTIES,
Application.SectionFlag.FIELDDEFINITIONS);
The DocumentService.getTargetApplication, however, returns a fixed section set that automatically includes both the properties and field definitions because these sections typically required when working with documents.
Creating a document in an Oracle I/PM application is a two step process. In the first step, the documents binary data is uploaded to the I/PM server using the DocumentContentService.uploadDocument operation. This operation returns a unique token (and upload token) that is then used in a subsequent call to DocumentService.createDocument to index the document into the application. This uploadToken is valid until the user logs out or until it is used in either a createDocument or updateDocument call. It may only be used once.
The upload operation accepts data in the form a javax.activation.DataHandler, which in turn wraps the document content as a javax.activation.DataSource, typically a javax.activation.FileDataSource. The javax.mail.util package also contains a ByteArrayDataSource which can wrap the document content from and InputStream. However, the ByteArrayDataSource will load the entire document into memory on the client before performing the upload, so it should be used with caution for very large documents Please refer to the Javadoc for the javax.activation and javax.mail.util packages for complete details on the use of DataHandlers and DataSources.
The Document.FieldValue class in the Oracle I/PM API is used to provide document metadata when indexing a document. FieldValues are passed to createDocument as a java.util.List of Document.FieldValue instances. Each FieldValue in the list will map to a FieldDefinition in the application.
The Document.FieldValue object behaves similarly to NameId definition classes in that they can be defined to map to an application field definition by either Field ID or Field Name. If both are supplied, then the ID value supersedes the name value.
A Document.FieldValue also contains a value property. The type of the value must be be compatible with the I/PM FieldType of the field definition. The I/PM type of the value is automatically determined by the Java type used. The following table lists the I/PM field types and the corresponding compatible Java types.
| I/PM Field Type | Java Type |
|---|---|
| FieldType.Date | java.util.Date, java.util.GregorianCalendar |
| FieldType.Decimal | java.math.BigDecimal, float, decimal |
| FieldType.Number | Integer, Long, |
| FieldType.Text | String |
In the table, the Java types in bold are the native types associated with the FieldType. The FieldValue will coerce other types in the table into the native type. Caution should be used when using types other than the native types since precision on the value may sometime be lost during the coercion process.
When FieldValues are use with createDocument, all field values that are defined as required must be supplied. For fields that are not required, it is also possible to deliberately set the value to null by including the FieldValue in the list but setting the FieldValue's value to null. When doing this, the FieldValue cannot determine the necessary field type based on the null Java type, so the FieldValue constructor accepting an I/PM FieldType must be used.
The following sample demonstrates the basic concepts discussed in this section.
package devguidesamples;
import java.math.BigDecimal;
import java.util.ArrayList;
import java.util.Date;
import java.util.List;
import java.util.Locale;
import javax.activation.DataHandler;
import javax.activation.FileDataSource;
import oracle.imaging.Application;
import oracle.imaging.ApplicationService;
import oracle.imaging.BasicUserToken;
import oracle.imaging.Document;
import oracle.imaging.DocumentContentService;
import oracle.imaging.DocumentService;
import oracle.imaging.ImagingException;
import oracle.imaging.NameId;
import oracle.imaging.ServicesFactory;
import oracle.imaging.UserToken;
public class CreateDocumentSample {
public static void main(String[] args) {
try { // try-catch
UserToken credentials = new BasicUserToken("ipmuser", "ipmuserpwd");
ServicesFactory servicesFactory =
ServicesFactory.login(credentials, Locale.US,
"http://ipmhost:16000/imaging/ws");
try { // try-finally to ensure logout
DocumentService docService = servicesFactory.getDocumentService();
DocumentContentService docContentService =
servicesFactory.getDocumentContentService();
NameId invoicesAppNameId = null;
// List the viewable applications to confirm that "Invoices" exists
List<NameId> appsList =
docService.listTargetApplications(Document.Ability.CREATEDOCUMENT);
for (NameId nameId: appsList) {
if (nameId.getName().equals("Invoices")) {
invoicesAppNameId = nameId;
}
}
if (invoicesAppNameId == null) {
System.out.println("Invoices application not found.");
return;
}
// Upload document content
String fileName = "C:/PathToImages/invoice1234.tif";
DataHandler fileData = new DataHandler(new FileDataSource(fileName));
String uploadToken = docContentService.uploadDocument(fileData,
"invoice1234.tif");
// Index the document
List<Document.FieldValue> fieldValues = new
ArrayList<Document.FieldValue>();
fieldValues.add(new Document.FieldValue("Invoice Number", 1234));
fieldValues.add(new Document.FieldValue("Purchase Order", 4321));
fieldValues.add(new Document.FieldValue("Vendor", "Acme Supply"));
fieldValues.add(new Document.FieldValue("Amount", new
BigDecimal("99.95")));
fieldValues.add(new Document.FieldValue("Receive Date", new Date()));
docService.createDocument(uploadToken, invoicesAppNameId,
fieldValues, true);
}
finally {
if (servicesFactory != null) {
servicesFactory.logout();
}
}
}
catch (ImagingException e) {
System.out.println(e.getMessage());
}
}
}