|
You can programmatically add a Watched Folder endpoint
to a service by using the LiveCycle Java API. By adding
a Watched Folder endpoint, you enable users to place a file (such
as a PDF file) in a folder. When the file is placed in the folder,
the configured service is then invoked and manipulates the file. After
the service performs the specified operation, it saves the modified
file in a specified output folder. A watched folder is configured
to be scanned at a fixed rate interval or with a cron schedule,
such as every Monday, Wednesday, and Friday at noon.
For the purposes of programmatically adding a Watched Folder
endpoint to a service, consider the following short-lived process
named EncryptDocument. (See Understanding LiveCycle Processes.)
This process accepts an unsecured PDF document as an input value
and then passes the unsecured PDF document to the Encryption service’s EncryptPDFUsingPassword operation.
The PDF document is encrypted with a password, and the password-encrypted
PDF document is the output value of this process. The name of the
input value (the unsecured PDF document) is InDoc and
the data type is com.adobe.idp.Document. The name
of the output value (the password-encrypted PDF document) is SecuredDoc and
the data type is com.adobe.idp.Document.
Note: You cannot add a Watched Folder endpoint by
using web services.
Summary of stepsTo add a Watched Folder endpoint to a service, perform
the following tasks:
Include project files.
Create an EndpointRegistryClient object.
Set Watched Folder endpoint attributes.
Specify configuration values.
Define input parameter values.
Define an output parameter value.
Create a Watched Folder endpoint.
Enable the endpoint.
Include project filesInclude the necessary files in your development
project. If you are creating a client application by using Java,
include the necessary JAR files. If you are using web services,
make sure that you include the proxy files.
The following
JAR files must be added to your project’s class path:
adobe-livecycle-client.jar
adobe-usermanager-client.jar
adobe-utilities.jar (required if LiveCycle is deployed
on JBoss Application Server)
jbossall-client.jar (required if LiveCycle is deployed
on JBoss Application Server)
For information about
the location of these JAR files, see Including LiveCycle Java library files.
Create an EndpointRegistry Client objectTo programmatically
add a Watched Folder endpoint, you must create an EndpointRegistryClient object.
Set Watched Folder endpoint attributesTo create a Watched
Folder endpoint for a service, specify the following values:
Connector identifier: Specifies the type of endpoint
that is created. To create a Watched Folder endpoint, specify WatchedFolder.
Description: Specifies the description of the endpoint.
Name: Specifies the name of the endpoint.
Service identifier: Specifies the service to which
the endpoint belongs. For example, to add a Watched Folder endpoint
to the process that is introduced in this section (a process becomes
a service when activated using Workbench), specify EncryptDocument.
Operation name: Specifies the name of the operation
that is invoked by using the endpoint. Typically, when creating
a Watched Folder endpoint for a service that originated from a process
created in Workbench, the name of the operation is invoke.
Specify configuration valuesYou must specify configuration values
for a Watched Folder endpoint when programmatically adding a Watched
Folder endpoint to a service. These configuration values are specified
by an administrator if a Watched Folder endpoint is added by using
Administration Console.
The following list specifies configuration
values that are set when programmatically adding a Watched Folder
endpoint to a service:
url: Specifies the watched
folder location. In a clustered environment, this value must point
to a shared network folder that is accessible from every computer
in the cluster.
asynchronous: Identifies the invocation type as asynchronous
or synchronous. Transient and synchronous processes can only be
invoked synchronously. The default value is true. Asynchronous is
recommended.
cronExpression: Used by quartz to schedule the polling
of the input directory. For details about configuring the cron expression,
see http://quartz.sourceforge.net/javadoc/org/quartz/CronTrigger.html.
purgeDuration: This is a mandatory attribute. Files
and folders in the result folder are purged when they are older
than this value. This value is measured in days. This attribute
is useful in ensuring the result folder does not become full. A
value of -1 days indicates to never delete the results folder. The
default value is -1.
repeatInterval: The interval, in seconds, for scanning
the Watched Folder for input. Unless throttling is enabled, this
value should be longer than the time to process an average job;
otherwise, the system may become overloaded. The default value is
5.
repeatCount: The number of times a Watched Folder
scans the folder or directory. A value of -1 indicates indefinite
scanning. The default value is -1.
throttleOn: Limits the number of Watched Folder jobs
that can be processed at any given time. The maximum number of jobs
is determined by the batchSize value.
userName: The user name used when invoking a target
service from the Watched Folder. This value is mandatory. The default
value is SuperAdmin.
domainName: The user’s domain. This value is mandatory.
The default value is DefaultDom.
batchSize: The number of files or folders to be picked
up per scan. Use this value to prevent an overload on the system;
scanning too many files at one time can result in a crash. The default
value is 2.
waitTime: The time, in milliseconds, to wait before
scanning a folder or file after creation. For example, if wait time
is 36,000,000 milliseconds (one hour) and the file was created one
minute ago, this file is picked up after 59 or more minutes have
passed. This attribute is useful to ensure that a file or folder
is completely copied to the input folder. For example, if you have
a large file to process and the file takes ten minutes to download,
set the wait time to 10*60 *1000 milliseconds. This setting prevents
the watched folder from scanning the file if it has not been waiting
for ten minutes. The default value is 0.
excludeFilePattern: The pattern that a watched folder
uses to determine which files and folders to scan and pick up. Any
file or folder that has this pattern will not be scanned for processing.
This setting is useful when the input is a folder that contains
multiple files. The contents of the folder can be copied into a
folder that has a name that will be picked up by the watched folder.
This step prevents the watched folder from picking up a folder for processing
before the folder is completely copied into the input folder. For example,
if the excludeFilePattern value is data*, all files
and folders that match data* are not picked up.
This includes files and folders named data1, data2,
and so on. Additionally, the pattern can be supplemented with wildcard
patterns to specify file patterns. The watched folder modifies the regular
expression to support wildcard patterns such as *.* and *.pdf. These
wildcard patterns are not supported by regular expressions.
includeFilePattern: The pattern that the watched folder
uses to determine which folders and files to scan and pick up. For
example, if this value is *, all files and folders
that match input* are picked up. This includes
files and folders named input1, input2,
and so on. The default value is *. This value indicates
all files and folders. Additionally, the pattern can be supplemented with
wildcard patterns to specify file patterns. The watched folder modifies
the regular expression to support wildcard patterns such as *.* and *.pdf. These
wildcard patterns are not supported by regular expressions. This
value is a mandatory.
resultFolderName: The folder where the saved results
are stored. This location can be an absolute or a relative directory
path. If the results do not appear in this folder, check the failure
folder. Read-only files are not processed and will be saved in the
failure folder. The default value is result/%Y/%M/%D/.
This is the results folder inside the watched folder.
preserveFolderName: The location where files are stored
after successful scanning and pickup. This location can be an absolute,
a relative, or a null directory path. The default value is preserve/%Y/%M/%D/.
failureFolderName: The folder where failure files
are saved. This location is always relative to the watched folder.
Read-only files are not processed and will be saved in the failure
folder. The default value is failure/%Y/%M/%D/.
preserveOnFailure: Preserve input files in case of
failure to execute the operation on a service. The default value
is true.
overwriteDuplicateFilename: When set to true, files
in the results folder and preserve folder are overwritten. When
set to false, files and folders that have a numeric index suffix
are used for the name. The default value is false.
Define input parameter valuesWhen creating a Watched Folder
endpoint, you must define input parameter values. That is, you must
describe the input values that are passed to the operation that
is invoked by the watched folder. For example, consider the process
introduced in this topic. It has one input value named InDoc and
its data type is com.adobe.idp.Document. When creating
a Watched Folder endpoint for this process (after a process is activated,
it becomes a service), you must define the input parameter value.
To
define input parameter values required for a Watched Folder endpoint,
specify the following values:
Input parameter name:
The name of the input parameter. The name of an input value is specified
in Workbench for a process. If the input value belongs to a service
operation (a service that is not a process created in Workbench),
the input name is specified in the component.xml file. For example,
the name of the input parameter for the process introduced in this
section is InDoc.
Mapping type: Used
to configure the input values required to invoke the service operation.
There are two types of mapping types:
Literal:
The Watched Folder endpoint uses the value entered in the field
as it is displayed. All basic Java types are supported. For example,
if an API uses input such as String, long, int, and Boolean, the
string is converted into the proper type and the service is invoked.
Variable: The value entered is a file pattern
that the watched folder uses to pick the input. For example, if
you select Variable for the mapping type and the input document
must be a PDF file, you can specify *.pdf as the
mapping value.
Mapping value: Specifies
the value of the mapping type. For example, if you select a Variable mapping
type, you can specify *.pdf as the file pattern.
Data type:
Specifies the data type of the input value(s). For example, the
data type of the input value of the process introduced in this section
is com.adobe.idp.Document.
Define an output parameter valueWhen creating a Watched Folder
endpoint, you must define an output parameter value. That is, you
must describe the output value that is returned by the service that
is invoked by the Watched Folder endpoint. For example, consider
the process introduced in this topic. It has an output value named SecuredDoc and its
data type is com.adobe.idp.Document. When creating
a Watched Folder endpoint for this process (after a process is activated,
it becomes a service), you must define the output parameter value.
To
define an output parameter value required for a Watched Folder endpoint, specify
the following values:
Output parameter name: The name
of the output parameter. The name of a process output value is specified
in Workbench. If the output value belongs to a service operation
(a service that is not a process created in Workbench), the output
name is specified in the component.xml file. For example, the name
of the output parameter for the process introduced in this section
is SecuredDoc.
Mapping type: Used
to configure the output of the service and operation. The following
options are available:
If the service returns a single
object (a single document), the pattern is %F.pdf and
the source destination is sourcefilename.pdf. For example, the process
introduced in this section returns a single document. As a result,
the mapping type can be defined as %F.pdf (%F means
use the given file name). The pattern %E specifies
the extension of the input document.
If the service returns a list, the pattern is Result\%F\,
and the source destination is Result\sourcefilename\source1 (output
1) and Result\sourcefilename\source2 (output 2).
If the service returns a map, the pattern is Result\%F\,
and the source destination is Result\sourcefilename\file1 and Result\sourcefilename\file2.
If the map has more than one object, the pattern is Result\%F.pdf and
the source destination is Result\sourcefilename1.pdf (output 1), Result\sourcefilenam2.pdf
(output 2), and so on.
Data type: Specifies
the data type of the return value. For example, the data type of
the return value of the process introduced in this section is com.adobe.idp.Document.
Create a Watched Folder endpointAfter you set the endpoint’s
attributes, configuration values, and define input and output parameter
values, you must create the Watched Folder endpoint.
Enable the endpointAfter you create a Watched Folder endpoint,
you must enable it. When the endpoint is enabled, it can be used
to invoke the service. After you enable the endpoint, you can view
it within Administration Console.
Add a Watched Folder endpoint using the Java APIAdd a Watched Folder endpoint by using the LiveCycle Java API:
Include project files.
Include client JAR files,
such as adobe-livecycle-client.jar, in your Java project’s class
path.
Create an EndpointRegistry Client object.
Set Watched Folder endpoint attributes.
Create
a CreateEndpointInfo object by using its constructor.
Specify the connector identifier value by invoking the CreateEndpointInfo object’s setConnectorId method
and passing the string value WatchedFolder.
Specify the description of the endpoint by invoking the CreateEndpointInfo object’s setDescription method
and passing a string value that describes the endpoint.
Specify the name of the endpoint by invoking the CreateEndpointInfo object’s setName method
and passing a string value that specifies the name.
Specify the service to which the endpoint belongs by invoking
the CreateEndpointInfo object’s setServiceId method
and passing a string value that specifies the service name.
Specify the operation that is invoked by invoking the CreateEndpointInfo object’s setOperationName method
and passing a string value that specifies the operation name. Typically,
when creating a Watched Folder endpoint for a service that originated
from a process created in Workbench, the name of the operation is
invoke.
Specify configuration values.
For each configuration
value to set for the Watched Folder endpoint, you must invoke the CreateEndpointInfo object’s setConfigParameterAsText method.
For example, to set the url configuration value,
invoke the CreateEndpointInfo object’s setConfigParameterAsText method
and pass the following string values:
A string value
that specifies the name of the configuration value. When setting
the url configuration value, specify url.
A string value that specifies the value of the configuration
value. When setting the url configuration value,
specify the watched folder location.
Define input parameter values.
Define an input parameter
value by invoking the CreateEndpointInfo object’s setInputParameterMapping method
and pass the following values:
A string value that
specifies the name of the input parameter. For example, the name
of the input parameter for the EncryptDocument service is InDoc.
A string value that specifies the data type of the input
parameter. For example, the data type of the InDoc input
parameter is com.adobe.idp.Document.
A string value that specifies the mapping type. For example,
you can specify variable.
A string value that specifies the mapping type value. For
example, you can specify *.pdf as the file pattern.
Note: Invoke the setInputParameterMapping method
for each input parameter value to define. Because the EncryptDocument
process has only one input parameter, you need to invoke this method
once.
Define an output parameter value.
Define an output
parameter value by invoking the CreateEndpointInfo object’s setOutputParameterMapping method
and pass the following values:
A string value that
specifies the name of the output parameter. For example, the name
of the output parameter for the EncryptDocument service is SecuredDoc.
A string value that specifies the data type of the output
parameter. For example, the data type of the SecuredDoc output
parameter is com.adobe.idp.Document.
A string value that specifies the mapping type. For example,
you can specify %F.pdf.
Create a Watched Folder endpoint.
Create the endpoint
by invoking the EndpointRegistryClient object’s createEndpoint method
and passing the CreateEndpointInfo object. This
method returns an Endpoint object that represents
the Watched Folder endpoint.
Enable the endpoint.
Enable the endpoint by invoking
the EndpointRegistryClient object’s enable method
and passing the Endpoint object that was returned
by the createEndpoint method.
Watched folder configuration values constant fileThe QuickStart: Adding a Watched Folder endpoint using the Java API uses
a constant file that must be part of your Java project in order
to compile the quick start. This constant file represents configuration
values that must be set when adding a Watched Folder endpoint. The
following Java code represents the constant file. For information
about these configuration values, see Specify configuration values.
/**
* This class contains constants that can be used when setting Watched Folder
* configuration values
*/
public final class WatchedFolderEndpointConfigConstants {
public static final String PROPERTY_FILEPROVIDER_URL = "url";
public static final String PROPERTY_PROPERTY_ASYNCHRONOUS = "asynchronous";
public static final String PROPERTY_CRON_EXPRESSION = "cronExpression";
public static final String PROPERTY_PURGE_DURATION = "purgeDuration";
public static final String PROPERTY_REPEAT_INTERVAL = "repeatInterval";
public static final String PROPERTY_REPEAT_COUNT = "repeatCount";
public static final String PROPERTY_THROTTLE = "throttleOn";
public static final String PROPERTY_USERNAMER = "userName";
public static final String PROPERTY_DOMAINNAME = "domainName";
public static final String PROPERTY_FILEPROVIDER_BATCH_SIZE = "batchSize";
public static final String PROPERTY_FILEPROVIDER_WAIT_TIME = "waitTime";
public static final String PROPERTY_EXCLUDE_FILE_PATTERN = "excludeFilePattern";
public static final String PROPERTY_INCLUDE_FILE_PATTERN = "excludeFilePattern";
public static final String PROPERTY_FILEPROVIDER_RESULT_FOLDER_NAME = "resultFolderName";
public static final String PROPERTY_FILEPROVIDER_PRESERVE_FOLDER_NAME = "preserveFolderName";
public static final String PROPERTY_FILEPROVIDER_FAILURE_FOLDER_NAME = "failureFolderName";
public static final String PROPERTY_FILEPROVIDER_PRESERVE_ON_FAILURE = "preserveOnFailure";
public static final String PROPERTY_FILEPROVIDER_OVERWRITE_DUPLICATE_FILENAME = "overwriteDuplicateFilename";
}
|
|
|
