7 Updating Documents

The Oracle I/PM 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.

This chapter has the following sections:

7.1 Uploading Document Content

Updating document content 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 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.2 Working with FieldValues

The Document.FieldValue class in the Oracle I/PM 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 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 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 I/PM FieldType must be used.

7.3 Update Document Sample

The following sample 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());
      }
   }
}