Aim of the DocumentAccessProvider interface is to decouple from the "physical" document file presentation.
Source for documents can be a regular File, a Stream, a String (in case of W2ML documents) or whatever. Renderers (at least as specified via the RenderLink interface) require a physical file as input, using a path representation resolveable from the renderers host system.
DocumentAccessProvider implementations act as mediators between the actual document input (Stream, String, File...) and the representation required by the renderers.
Both Renderer.openDocument methods take a DocumentAccessProvider object as second argument. So, as Renderer.openDocument is the starting point for any rendering operation, you cannot do much (if anything) without a suitable DocumentAccessProvider.
Fortunately, the basic usage is very simple:
package com.priint.renderer.example;
import java.nio.file.Paths;
import com.priint.comet.renderer.Constants;
import com.priint.comet.renderer.OpenedDocument;
import com.priint.comet.renderer.Renderer;
import com.priint.comet.renderer.exception.RendererException;
import com.priint.comet.renderer.io.providers.OpenInPlace;
public class AccessProviderExample {
public static void main(String args[]) {
String documentPath = "/path/to/my/document.w2ml";
try {
//
// + Renderer initialization & instance configuration...
//
Renderer renderer = new Renderer();
// open document based on string read from file
OpenedDocument document = renderer.openDocument(
Constants.ZEROCONF,
new OpenInPlace(Paths.get(documentPath))
);
//
// + further document processing
//
document.close();
}
catch (RendererException e) {
// exceptions during rendering
e.printStackTrace();
}
catch (Exception e) {
// exceptions during closing
e.printStackTrace();
}
}
}
In this example we use the OpenInPlace access provider, which simply takes the path of a (physical) to be opened as parameter. We expect, that this path cam be resolved in the JVM running the Java Rendering Library and in the renderer engine actually processing this document.
The Java Rendering Library contains some DocumentAccessProvider implementations for typical situation. Sooner or later you might need to add own implementations, if so please refer to the API documentation of the interface, which can be found here.
The common implementations found in the Java Rendering Library are described in the following.
com.priint.comet.renderer.io.providers.OpenInPlace just opens a document from the file system "in place".
Parameters:
java.nio.Path path: path of the document. The path must be resolveable in the JVM running the Java Rendering Library and in the rendering engine actually processing this document.Example: see above
com.priint.comet.renderer.io.providers.OpenInPlaceTranslated opens a document from the file system "in place" and allows path translation for the renderer engine.
Parameters:
java.nio.Path path: (local) path of the document. The path must be resolveable in the JVM running the Java Rendering Library.java.lang.String localPrefix: local prefix. This String will be replaced (from the beginning of path) by the String defined by remotePrefixjava.lang.String remotePrefix: remote prefix. String to insert instead of localPrefix for the remote (i.e. renderer engine) system
Example:
If your
/media/documents/ on the Linux machine and Z:\\Documents\ on Windows/media/documents/mydoc.ext (Java application / Linux host) can then be accessed on the renderer (Windows host) via Z:\\Documents\mydoc.ext
The code to instantiate an appropriate DocumentAccessProvider would be
import com.priint.comet.renderer.io.providers.OpenInPlace;
// ...
OpenInPlaceTranslated provider = new OpenInPlaceTranslated(
Paths.get("/media/documents/mydoc.ext"),
"/media/documents/",
"Z:\\\\Documents\\");
// etc.
com.priint.comet.renderer.io.provider.TmpCopyFromPath creates a temporary copy of the document. The original document will not be touched, so if you want to persist changes to the original document, you must handle this on client side.
Parameters:
java.nio.Path path path of the original documentClass<? extends com.priint.comet.renderer.DocumentType> type the document type to assume for this document. If not provided, the document type will be determined from the file extension.Example:
import com.priint.comet.renderer.io.providers.TmpCopyFromPath;
//
// ...
TmpCopyFromPath provider = new TmpCopyFromPath(
Paths.get("/PubServer4.2/userdata/documents/aio/578829902/578829908.indd"),
InDesignDocument.class);
// etc.
Just like OpenInPlaceTranslated, com.priint.comet.renderer.io.providers.TmpCopyFromPathTranslated allows path translations in heterogenous environments. Since we (most probably) cannot use the system default location for temporary storage, if the file should be accessed from other hosts, the second parameter is the local root path for the temporary folder to use.
Parameters:
java.nio.Path path path of the original documentjava.nio.Path tempPath local path of the temporary folderjava.lang.String tempPath remote path of the temporary folderClass<? extends com.priint.comet.renderer.DocumentType> type the document type to assume for this document. If not provided, the document type will be determined from the file extension.Example:
import com.priint.comet.renderer.io.providers.TmpCopyFromPathTranslated;
//
// ...
TmpCopyFromPathTranslated provider = new TmpCopyFromPathTranslated(
Paths.get("/PubServer4.2/userdata/documents/aio/578829902/578829908.indd"),
Paths.get("/media/SharedTmpFolder/"),
"Z:\\\\SharedTmpFolder\\");
// etc.
The original document will be copied to "/media/SharedTmpFolder" using a filename provided by the system. From the renderer (Windows host) point of view, the document can then be accessed via "Z:\\SharedTmpFolder\<tmpFileName>"
Similar to TmpCopyFromPath, com.priint.comet.renderer.io.providers.TmpCopyFromStream creates a (local) temporary copy of the document accessible through a java.io.InputStream. Since we cannot determine the document type from file extension, we must provide it in the TmpCopyFromStream constructor.
Parameters:
java.io.InputStream in input stream, from which we can read the document data.Class<? extends com.priint.comet.renderer.DocumentType> type the document type to assume for this document.Example:
import com.priint.comet.renderer.io.providers.TmpCopyFromStream; // // ... byte[] documentData; // read from file, network stream, ... TmpCopyFromStream provider = new TmpCopyFromStream( new com.priint.comet.renderer.io.TypedByteArrayInputStream(documentData, W2MLDocumentType.class), W2MLDocumentType.class); // etc.
Very similar to TmpCopyFromStream, com.priint.comet.renderer.io.providers.TmpCopyFromString uses a String as input for the document data.
Parameters:
java.lang.String in document data as stringClass<? extends com.priint.comet.renderer.DocumentType> type the document type to assume for this document.Example:
import com.priint.comet.renderer.io.providers.TmpCopyFromString; // // ... String documentData; // read from file, network stream, xml structure... TmpCopyFromString provider = new TmpCopyFromString( documentData, W2MLDocumentType.class); // etc.
You might be missing TmpCopyFromStreamTranslated or TmpCopyFromStringTranslated implementations.
At this stage, one should start to think about more sophisticated DocumentAccessProvider class hierarchy, particularly composition or aggregation. For now, we decided to cut off here and leave further (more customized, more sophisticated) implementations to the client side.
At least, the DocumentAccessProvider abstraction level hopefully enables developers to implement any solution applicable for the client environment.