Package com.logicaldoc.core.automation

# Class DocTool

java.lang.Object
com.logicaldoc.core.automation.DocTool

public class DocTool extends Object
Utility methods to handle documents from within Automation

Since:
  7.3
Author:
  Marco Meschieri - LogicalDOC

## Constructor Summary

Constructors
Constructor
Description
`DocTool()`

## Method Summary

Modifier and Type
Method
Description
`void`
`addNote(Document doc, String text, String username)`
Creates a new note for the whole document
`String`
`calculateNextVersion(String currentVersion, boolean major)`
Calculates what will be the next version specification.
`Document`
`clone(Document doc)`
Instantiate a new document that is a clone of the given one.
`Document`
`convert(Document doc, String format, String username)`
Convert a document in another format and saves the result in another file in the same folder
`void`
`convertPDF(Document doc)`
Converts a document in PDF format and saves it as ancillary resource of the document with suffix conversion-pdf.
`Document`
`copy(Document doc, String targetPath, boolean links, boolean notes, boolean security, String username)`
Copies a document into a target folder
`Document`
`copy(Document doc, String targetPath, String username)`
Copies a document into a target folder
`Document`
`copyResource(Document doc, String fileVersion, String suffix, String newFileName, String username)`
Copies a resource in a file in the same folder of the original document
`int`
`countPages(Document document)`
Counts the number of pages of a document
`Document`
`create(Document doc, File file, String username)`
Created a new document into the database
`Document`
`createAlias(Document originalDoc, Folder targetFolder, String type, String username)`
Creates an alias to a document
`Document`
`createAlias(Document originalDoc, String targetPath, String type, String username)`
Creates an alias to a document
`Folder`
`createPath(Document doc, String targetPath, String username)`
Creates a path, all existing nodes in the specified path will be reused
`void`
`delete(long docId, String username)`
Delete a document
`String`
`displayFileSize(Long size)`
Prints the size of a file in human readable form
`String`
`displayUrl(long tenantId, long docId)`
Builds the display url of a document(display permalink)
`String`
`displayUrl(Document doc)`
Builds the display url of a document(display permalink)
`String`
`displayUrl(DocumentHistory history)`
Builds the display url of a document(display permalink)
`DocumentEvent`
`documentEvent(String eventKey)`
`String`
`downloadTicket(long docId, boolean pdfConversion, Integer expireHours, Date expireDate, Integer maxDownloads, String username)`
Creates a new download ticket for a document
`String`
`downloadUrl(long docId)`
Builds the download url of a document(download permalink)
`String`
`downloadUrl(Document doc)`
Builds the download url of a document(download permalink)
`String`
`downloadUrl(DocumentHistory history)`
Builds the download url of a document(download permalink)
`Document`
`findById(long docId)`
Retrieves a document by it's identifier
`Document`
`findByPath(String path)`
Retrieves a document by it's path
`Document`
`findByPath(String path, Long tenantId)`
Retrieves a document by it's path
`Template`
`findTemplateById(long templateId)`
This method finds a template by ID
`Template`
`findTemplateByName(String name, long tenantId)`
This method finds a template by name
`List<DocumentHistory>`
`getHistories(long docId, DocumentEvent event)`
Retrieve the list of events of a document
`List<Long>`
`getIds(Collection<Document> docs)`
Converts a collection of documents in a collection of identifiers
`List<DocumentNote>`
`getNotes(long docId, long userId, String fileVersion)`
Lists the notes of a given document and visible to a given user
`List<DocumentNote>`
`getNotes(long docId, String fileVersion)`
Lists the notes of a given document
`String`
`getPath(Document doc)`
Calculates the full path of a document
`String`
`getText(Document document)`
Same as parse() but first it tries to get the text from the already built fulltext index
`void`
`initialize(Document doc)`
Initializes lazy loaded collections
`boolean`
`isDownloadAllowed(long documentId, long userId)`
`boolean`
`isPermissionAllowed(String permission, long documentId, long userId)`
This method checks if the given permission is enabled for a document and an user.
`boolean`
`isPreviewAllowed(long documentId, long userId)`
`boolean`
`isReadAllowed(long documentId, long userId)`
`boolean`
`isWriteAllowed(long documentId, long userId)`
`DocumentLink`
`link(Document doc1, Document doc2, String type)`
Links two documents
`void`
`lock(long docId, String username)`
Locks a document
`Document`
`merge(Collection<Document> documents, long targetFolderId, String fileName, String username)`
Merges a set of documents into a single PDF file
`void`
`move(Document doc, String targetPath, String username)`
Moves a document into a target folder
`String`
`parse(Document document, String fileVersion)`
Extracts the texts from a document, using the same analyzer used for the full-text processing.
`String`
`readAsString(long docId, String fileVersion, String suffix)`
Gets the content of a resource and reads it as a string
`void`
`store(Document doc)`
Saves / updates a document into the database
`void`
`store(Document doc, DocumentHistory transaction)`
Saves / updates a document into the database
`void`
`store(Document doc, String username)`
Saves / updates a document into the database
`void`
`unlock(long docId, String username)`
Unlocks a document
`String`
`viewTicket(long docId, boolean pdfConversion, Integer expireHours, Date expireDate, Integer maxDownloads, Integer maxViews, String username)`
Creates a new view ticket for a document
`void`
`writeToFile(long docId, String fileVersion, String suffix, String outputFile)`
Writes a resource in a file in the local file system

### Methods inherited from class java.lang.Object

`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### DocTool

public DocTool()

## Method Details

### downloadUrl

public String downloadUrl(long docId)
Builds the download url of a document(download permalink)

Parameters:
  `docId` - identifier of the document
Returns:
  the download permalink

### displayUrl

public String displayUrl(long tenantId, long docId)
Builds the display url of a document(display permalink)

Parameters:
  `tenantId` - identifier of the tenant
  `docId` - identifier of the document
Returns:
  the display permalink

### downloadUrl

public String downloadUrl(Document doc)
Builds the download url of a document(download permalink)

Parameters:
  `doc` - the document
Returns:
  the download permalink

### downloadUrl

public String downloadUrl(DocumentHistory history)
Builds the download url of a document(download permalink)

Parameters:
  `history` - object representing an event on a document
Returns:
  the download permalink

### displayUrl

public String displayUrl(Document doc)
Builds the display url of a document(display permalink)

Parameters:
  `doc` - the document
Returns:
  the display permalink

### displayUrl

public String displayUrl(DocumentHistory history)
Builds the display url of a document(display permalink)

Parameters:
  `history` - object representing an event on a document
Returns:
  the display permalink

### documentEvent

public DocumentEvent documentEvent(String eventKey)

### downloadTicket

public String downloadTicket(long docId, boolean pdfConversion, Integer expireHours, Date expireDate, Integer maxDownloads, String username)
Creates a new download ticket for a document

Parameters:
  `docId` - identifier of the document
  `pdfConversion` - if the pdf conversion should be downloaded instead of the original file
  `expireHours` - number of hours after which the ticket expires
  `expireDate` - a specific expiration date
  `maxDownloads` - number of downloads over which the ticket expires
  `username` - the user in whose name the method is run
Returns:
  the complete download ticket's URL

### viewTicket

public String viewTicket(long docId, boolean pdfConversion, Integer expireHours, Date expireDate, Integer maxDownloads, Integer maxViews, String username)
Creates a new view ticket for a document

Parameters:
  `docId` - identifier of the document
  `pdfConversion` - if the pdf conversion should be downloaded instead of the original file
  `expireHours` - number of hours after which the ticket expires
  `expireDate` - a specific expiration date
  `maxDownloads` - number of downloads over which the ticket expires
  `username` - the user in whose name the method is run
  `maxDownloads` - number of views over which the ticket expires
Returns:
  the complete download ticket's URL

### displayFileSize

public String displayFileSize(Long size)
Prints the size of a file in human readable form

Parameters:
  `size` - the file size
Returns:
  the human readable representation

### store

public void store(Document doc, DocumentHistory transaction)
Saves / updates a document into the database

Parameters:
  `doc` - the document to save
  `transaction` - entry to log the event

### store

public void store(Document doc)
Saves / updates a document into the database

Parameters:
  `doc` - the document to save

### store

public void store(Document doc, String username)
Saves / updates a document into the database

Parameters:
  `doc` - the document to save
  `username` - the user in whose name the method is run

### create

public Document create(Document doc, File file, String username)
Created a new document into the database

Parameters:
  `doc` - the document that carries the metadata
  `file` - the document's content
  `username` - the user in whose name the method is run
Returns:
  the created document

### initialize

public void initialize(Document doc)
Initializes lazy loaded collections

Parameters:
  `doc` - the document to initialize

### move

public void move(Document doc, String targetPath, String username) throws InterruptedException
Moves a document into a target folder

Parameters:
  `doc` - the document
  `targetPath` - the full path of the target folder
  `username` - the user in whose name the method is run
Throws:
  `InterruptedException` - In case or thread interruption

### clone

public Document clone(Document doc)
Instantiate a new document that is a clone of the given one. The returned clone is not persisted.

Parameters:
  `doc` - The source document to clone
Returns:
  The cloned document

### copy

public Document copy(Document doc, String targetPath, boolean links, boolean notes, boolean security, String username)
Copies a document into a target folder

Parameters:
  `doc` - the document
  `targetPath` - the full path of the target folder
  `links` - if the links must be copied too
  `notes` - if the notes must be copied too
  `security` - if the security settings must be copied too
  `username` - the user in whose name the method is run
Returns:
  the new document created

### copy

public Document copy(Document doc, String targetPath, String username)
Copies a document into a target folder

Parameters:
  `doc` - the document
  `targetPath` - the full path of the target folder
  `username` - the user in whose name the method is run
Returns:
  the new document created

### link

public DocumentLink link(Document doc1, Document doc2, String type)
Links two documents

Parameters:
  `doc1` - first document
  `doc2` - second document
  `type` - type of link(optional)
Returns:
  the created link

### createAlias

public Document createAlias(Document originalDoc, String targetPath, String type, String username) throws PersistenceException
Creates an alias to a document

Parameters:
  `originalDoc` - the original document to be referenced
  `targetPath` - the full path of the target folder
  `type` - the alias type(null for the original file or pdf for it's pdf conversion)
  `username` - the user in whose name the method is run
Returns:
  The new alias created
Throws:
  `PersistenceException` - Error in the database

### createAlias

public Document createAlias(Document originalDoc, Folder targetFolder, String type, String username)
Creates an alias to a document

Parameters:
  `originalDoc` - the original document to be referenced
  `targetFolder` - the folder that will contain the alias
  `type` - the alias type(null for the original file or pdf for it's pdf conversion)
  `username` - the user in whose name the method is run
Returns:
  The new alias created

### lock

public void lock(long docId, String username)
Locks a document

Parameters:
  `docId` - identifier of the document
  `username` - the user that locks the document

### unlock

public void unlock(long docId, String username)
Unlocks a document

Parameters:
  `docId` - identifier of the document
  `username` - the user that locks the document

### delete

public void delete(long docId, String username)
Delete a document

Parameters:
  `docId` - identifier of the document
  `username` - the user in whose name the method is run

### copyResource

public Document copyResource(Document doc, String fileVersion, String suffix, String newFileName, String username)
Copies a resource in a file in the same folder of the original document

Parameters:
  `doc` - The document
  `fileVersion` - The file version
  `suffix` - the suffix (eg conversion.pdf)
  `newFileName` - the file name of the new file
  `username` - the user in whose name the method is run
Returns:
  the document

### readAsString

public String readAsString(long docId, String fileVersion, String suffix)
Gets the content of a resource and reads it as a string

Parameters:
  `docId` - The document's identifier
  `fileVersion` - The file version
  `suffix` - The suffix
Returns:
  the file content as string

### writeToFile

public void writeToFile(long docId, String fileVersion, String suffix, String outputFile)
Writes a resource in a file in the local file system

Parameters:
  `docId` - The document's identifier
  `fileVersion` - The file version
  `suffix` - the suffix (eg conversion.pdf)
  `outputFile` - the user in name of which to take this action

### convertPDF

public void convertPDF(Document doc)
Converts a document in PDF format and saves it as ancillary resource of the document with suffix conversion-pdf. If the conversion already exists, nothing will be done.

Parameters:
  `doc` - the document to convert

### convert

public Document convert(Document doc, String format, String username)
Convert a document in another format and saves the result in another file in the same folder

Parameters:
  `doc` - the document to convert
  `format` - it is the output format(e.g. pdf, txt, ...)
  `username` - the user in whose name the method is run
Returns:
  the generated conversion document

### merge

public Document merge(Collection<Document> documents, long targetFolderId, String fileName, String username)
Merges a set of documents into a single PDF file

Parameters:
  `documents` - the list of documents to merge(the order counts)
  `targetFolderId` - identifier of the target folder
  `fileName` - name of the output file(must ends with .pdf)
  `username` - the user in whose name the method is run
Returns:
  the generated merged document

### findById

public Document findById(long docId)
Retrieves a document by it's identifier

Parameters:
  `docId` - identifier of the document
Returns:
  the document object

### findByPath

public Document findByPath(String path)
Retrieves a document by it's path

Parameters:
  `path` - full path of the document
Returns:
  the document object

### findByPath

public Document findByPath(String path, Long tenantId)
Retrieves a document by it's path

Parameters:
  `path` - full path of the document
  `tenantId` - identifier of the tenant(optional)
Returns:
  the document object

### getPath

public String getPath(Document doc)
Calculates the full path of a document

Parameters:
  `doc` - the document to inspect
Returns:
  the full path

### getIds

public List<Long> getIds(Collection<Document> docs)
Converts a collection of documents in a collection of identifiers

Parameters:
  `docs` - the input collection
Returns:
  the list of all the IDs of the documents in the input collection

### createPath

public Folder createPath(Document doc, String targetPath, String username)
Creates a path, all existing nodes in the specified path will be reused

Parameters:
  `doc` - document used to take the root folder in case the `targetPath` represents a relative path
  `targetPath` - absolute or relative(in relation to the document's parent folder) path to be created
  `username` - the user in whose name the method is run
Returns:
  the folder leaf of the path

### getHistories

public List<DocumentHistory> getHistories(long docId, DocumentEvent event)
Retrieve the list of events of a document

Parameters:
  `docId` - identifier of the document
  `event` - event name, optional
Returns:
  list of histories

### addNote

public void addNote(Document doc, String text, String username)
Creates a new note for the whole document

Parameters:
  `doc` - the document
  `text` - text of the note
  `username` - username of the user in name of which this action is taken

### getNotes

public List<DocumentNote> getNotes(long docId, String fileVersion)
Lists the notes of a given document

Parameters:
  `docId` - identifier of the document
  `fileVersion` - version of the file, optional
Returns:
  the list of notes

### getNotes

public List<DocumentNote> getNotes(long docId, long userId, String fileVersion)
Lists the notes of a given document and visible to a given user

Parameters:
  `docId` - identifier of the document
  `userId` - identifier of the user
  `fileVersion` - version of the file, optional
Returns:
  the list of notes

### calculateNextVersion

public String calculateNextVersion(String currentVersion, boolean major)
Calculates what will be the next version specification. @see `Version.getNewVersionName(String, boolean)`

Parameters:
  `currentVersion` - the current version(e.g. 1.1, 2.15, ...)
  `major` - if the new release must be a major release
Returns:
  the new version

### findTemplateByName

public Template findTemplateByName(String name, long tenantId)
This method finds a template by name

Parameters:
  `name` - Name of the template
  `tenantId` - Identifier of the owning tenant
Returns:
  Template with given name

### findTemplateById

public Template findTemplateById(long templateId)
This method finds a template by ID

Parameters:
  `templateId` - Identifier of the template
Returns:
  Template with given name

### countPages

public int countPages(Document document)
Counts the number of pages of a document

Parameters:
  `document` - the document
Returns:
  the number of pages

### parse

public String parse(Document document, String fileVersion)
Extracts the texts from a document, using the same analyzer used for the full-text processing.

Parameters:
  `document` - The document to elaborate
  `fileVersion` - Optional file version to consier
Returns:
  the extracted texts

### getText

public String getText(Document document)
Same as parse() but first it tries to get the text from the already built fulltext index

Parameters:
  `document` - The document to elaborate
Returns:
  the extracted texts

### isPermissionAllowed

public boolean isPermissionAllowed(String permission, long documentId, long userId)
This method checks if the given permission is enabled for a document and an user.

Parameters:
  `permission` - the permission to check
  `documentId` - ID of the folder
  `userId` - ID of the user
Returns:
  if the permission is granted to the user

### isWriteAllowed

public boolean isWriteAllowed(long documentId, long userId)

### isReadAllowed

public boolean isReadAllowed(long documentId, long userId)

### isPreviewAllowed

public boolean isPreviewAllowed(long documentId, long userId)

### isDownloadAllowed

public boolean isDownloadAllowed(long documentId, long userId)