7 Updating a Document
This chapter has the following sections:
7.1 About Updating a Document
The Imaging API provides the DocumentService.updateDocument operation for updating both a document's metadata as well as a document's content. This operation accepts both an uploadToken returned from a DocumentContentService.uploadDocument operation, and a List for FieldValue instances containing field value changes. Either or both of these parameters may be supplied meaning that the updated can either be a field value only update, a document content only update, or it can update both field values and content. At the end of the chapter, Example 7-1 provides a code sample of the topics presented here.
7.2 Uploading Revised Document Content
Updating document content in an Imaging application is a two step process. In the first step, the documents binary data is uploaded to the Imaging server using the DocumentContentService.uploadDocument operation. This operation returns a unique upload token that is then used in a subsequent call to DocumentService.updateDocument 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.
7.3 Updating Metadata for a Document
The Document.FieldValue class in the Imaging API is used to provide document metadata when indexing a document. FieldValues are passed to udpateDocument as a java.util.List of Document.FieldValue instances. Each FieldValue in the list will maps 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 compatible with the Imaging FieldType of the field definition. The Imaging type of the value is automatically determined by the Java type used. The following table lists the Imaging field types and the corresponding compatible java types.
Imaging 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 updateDocument, the list need not contain every field defined in the document's application. Only those field values needing to change should be supplied. And field that is not supplied with be ignored when updating the document. For fields that are not defines as required, it is also possible to deliberately set a document field 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 Imaging FieldType must be used.
7.4 Update Document Sample
Example 7-1 demonstrates the basic concepts discussed in this section:
Example 7-1 Sample Document Update
package devguidesamples; import java.io.FileOutputStream; import java.io.IOException; 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.BasicUserToken; import oracle.imaging.Document; import oracle.imaging.DocumentContentService; import oracle.imaging.DocumentService; import oracle.imaging.ImagingException; import oracle.imaging.NameId; import oracle.imaging.RenderOptions; import oracle.imaging.RenderPage; import oracle.imaging.RenderResult; import oracle.imaging.Rendition; import oracle.imaging.Search; import oracle.imaging.SearchArgument; import oracle.imaging.SearchService; import oracle.imaging.SearchValue; import oracle.imaging.ServicesFactory; import oracle.imaging.TypedValue; import oracle.imaging.UserToken; public class UpdateDocumentSample { public static void main(String[] args) throws IOException { 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 SearchService searchService = servicesFactory.getSearchService(); DocumentService docService = servicesFactory.getDocumentService(); DocumentContentService docContentService = servicesFactory.getDocumentContentService(); // The find the document with invoice number 1234 using the Invoices search List<SearchArgument> searchArguments = new ArrayList<SearchArgument>(); SearchValue searchValue = new SearchValue(SearchValue.Type.NUMBER, 1234); SearchArgument searchArgument = new SearchArgument("Invoice Number", searchValue); searchArgument.setOperatorValue(Search.Operator.EQUAL); searchArguments.add(searchArgument); Search.ResultSet resultSet = searchService.executeSavedSearch(new NameId("Invoices"), searchArguments); if (resultSet.getTotalResults() == 0) { System.out.println("Document not found"); } String documentId = resultSet.getResults().get(0).getDocumentId(); // update field values only. List<Document.FieldValue> fieldValues = new ArrayList<Document.FieldValue>(); fieldValues.add(new Document.FieldValue("Amount", new BigDecimal("99.95"))); docService.updateDocument(documentId, null, fieldValues, false); // update document content String fileName = "C:/PathToImages/NewInvoice1234.tif"; DataHandler fileData = new DataHandler(new FileDataSource(fileName)); String uploadToken = docContentService.uploadDocument(fileData, "invoice1234.tif"); docService.updateDocument(documentID, uploadToken, null, false); // update field values and document content at once fieldValues = new ArrayList<Document.FieldValue>(); fieldValues.add(new Document.FieldValue("Receive Date", new Date())); //now fileName = "C:/PathToImages/AnotherNewInvoice1234.tif"; fileData = new DataHandler(new FileDataSource(fileName)); uploadToken = docContentService.uploadDocument(fileData, "invoice1234.tif"); docService.updateDocument(documentID, uploadToken, fieldValues, false); } finally { if (servicesFactory != null) { servicesFactory.logout(); } } } catch (ImagingException e) { System.out.println(e.getMessage()); } } }