6 Retrieving Documents

The Oracle I/PM API provides several document retrieval operations on the DocumentContentService. All of the retrieval methods accept the unique document identifier as input and return document content as a javax.activation.DataHandler.

When processing the DataHandler results, calling code should assume that the DataHandler is a wrapper around an open stream to the server and should process the results immediately, either by persisting the content to an output stream, such as a file, using the DataHandler.writeTo method, or by reading the input stream directly by using the DataHandler.getInputStream method. If the input stream is accessed directly, the caller must be sure to close the stream when the reading of the stream is complete.

Some of the retrieval methods that perform rendering operations on the original document in its native format, also accept additional parameters for controlling the rendering process.

This chapter has the following sections:

Section 6.1, "Retrieving an Original Document"
Section 6.2, "Retrieving a Rendition with Annotations"
Section 6.3, "Retrieving Individual Pages"
Section 6.4, "Retrieve Document Sample"

6.1 Retrieving an Original Document

The original document is retrieved using the DocumentContentService.retrieve operation. This operation is the simple retrieval method and takes only the document ID as an argument. It returns the binary content of the document as a DataHandler. The Oracle I/PM render engine does no processing on the document in this case. Note, however, that this operation will return an exception if the document has secure annotations associated with it and the calling user does not have permissions to remove those annotations.

6.2 Retrieving a Rendition with Annotations

The document can be rendered along with its associated annotations using the DocumentContentService.retrieveRendition operation. This operation accepts a number of arguments including the documentId and a flag indicating whether or not to include annotations. It also includes a parameter for specify the page set that is to be rendered. Specifying multiple pages for this parameter will results in single, multi-page document containing only those pages. Passing a null, or page zero, for this parameter will render the entire document. Refer the Javadoc for the retrieveRendition for complete details other parameters to the method.

The retrieveRendition method returns a Rendition class instance. The DataHandler containing the document content is accessible from the Rendition.getContent() method.

6.3 Retrieving Individual Pages

While the retrieveRendition method is used to return a single, possible multiple page rendition of the document, individual pages can be retrieved using the DocumentContentService.retrievePage. This method provides detailed control over how the page is rendered by accepting a RenderOptions class instance. RenderOptions provides options for specifying page rotation, page scaling, fit mode, output format, and others.

The retrievePage method returns a RenderResult class instance, which contains a List of RenderPage. The DataHandler content for page is accessible from RenderPage.getPageData().

6.4 Retrieve Document Sample

The following sample demonstrates the basic concepts discussed in this section.

Example 6-1 Sample Document Retrieval

package devguidesamples;
 
import java.io.FileOutputStream;
 
import java.io.IOException;
import java.io.InputStream;
 
import java.util.ArrayList;
import java.util.List;
import java.util.Locale;
 
import javax.activation.DataHandler;
 
import oracle.imaging.BasicUserToken;
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.UserToken;
 
public class RetrieveDocumentSample {
   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();
            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();
            String documentName = resultSet.getResults().get(0).getDocument().getName();
 
            DataHandler fileData = null;
            FileOutputStream outputStream = null;
            
            // retrieve original native document content.
            fileData = docContentService.retrieve(documentId);
            outputStream = new FileOutputStream(documentName);
            fileData.writeTo(outputStream);
            outputStream.close();
            
            // Retrieve a document rendition with annotations
            Rendition rendition = docContentService.retrieveRendition(documentId, 
                                                     true, 
                                                     true, 
                                                     RenderOptions.RenditionOutput.ORIGINALORTIFF, 
                                                     null);
            
            fileData = rendition.getContent();
            outputStream = new FileOutputStream(documentName);
            fileData.writeTo(outputStream);
            outputStream.close();  
            
            //Render a specific page to JPEG format.
            RenderOptions renderOptions = new RenderOptions();
            renderOptions.setPageNumber(2);
            renderOptions.setFormat(RenderOptions.OutputFormat.JPEG);
            RenderResult result = docContentService.retrievePage(documentId, renderOptions); 
            RenderPage page = result.getPages()[0];
            
            fileData = page.getPageData();
            outputStream = new FileOutputStream(documentName);
            fileData.writeTo(outputStream);
            outputStream.close();  
         }
         finally {
            if (servicesFactory != null) {
               servicesFactory.logout();
            }
         }
      }
      catch (ImagingException e) {
         System.out.println(e.getMessage());
      }
   }
}