Inbound Operation File Polling

4-36 Oracle Fusion Middleware Users Guide for Technology Adapters Figure 4–20 The Adapter Configuration Wizard - Specifying Incoming Files The following sections describe the file directory information to specify: ■ Section 4.3.1.2.1, Specifying Inbound Physical or Logical Directory Paths in SOA Composite ■ Section 4.3.1.2.2, Archiving Successfully Processed Files ■ Section 4.3.1.2.3, Deleting Files After Retrieval

4.3.1.2.1 Specifying Inbound Physical or Logical Directory Paths in SOA Composite

You can specify inbound directory names as physical or logical paths in the composite involving Oracle BPEL PM and Mediator. Physical paths are values such as c:\inputDir. In the composite, logical properties are specified in the inbound JCA file and their logical-physical mapping is resolved by using binding properties. You specify the logical parameters once at design time, and you can later modify the physical directory name as needed. For example, the generated inbound JCA file looks as follows for the logical input directory name InputFileDir. ?xml version=1.0 encoding=UTF-8? adapter-config name=FlatStructureIn adapter=File Adapter xmlns=http:platform.integration.oracleblocksadapterfwmetadata connection-factory location=eisFileAdapter UIincludeWildcard=.txt adapterRef= Note: If the inbound Oracle File Adapter is configured for polling multiple directories for incoming files, then all the top-level directories inbound directories where the input file appears must exist before the file reader starts polling these directories. Oracle JCA Adapter for FilesFTP 4-37 endpoint-activation operation=Read activation-spec className=oracle.tip.adapter.file.inbound.FileActivationSpec property name=UseHeaders value=false property name=LogicalDirectory value=InputFileDir property name=Recursive value=true property name=DeleteFile value=true property name=IncludeFiles value=.\.txt property name=PollingFrequency value=10 property name=MinimumAge value=0 property name=OpaqueSchema value=false activation-spec endpoint-activation adapter-config In the composite.xml file, you then provide the physical parameter values in this case, the directory path of the corresponding logical ActivationSpec or InteractionSpec. This resolves the mapping between the logical directory name and actual physical directory name. service name=FlatStructureIn interface.wsdl interface=http:xmlns.oracle.compcbpeladapterfileFlatStructureInwsdl.inter faceRead_ptt binding.jca config=FlatStructureIn_file.jca property name= InputFileDir type=xs:string many=false source= override=may homeuserinputDirproperty binding.jca service

4.3.1.2.2 Archiving Successfully Processed Files

This option enables you to specify a directory in which to place successfully processed files. You can also specify the archive directory as a logical name. In this case, you must follow the logical-to-physical mappings described in Section 4.3.1.2.1, Specifying Inbound Physical or Logical Directory Paths in SOA Composite.

4.3.1.2.3 Deleting Files After Retrieval

This option enables you to specify whether to delete files after a successful retrieval. If this check box is not selected, processed files remain in the inbound directory but are ignored. Only files with modification dates more recent than the last processed file are retrieved. If you place another file in the inbound directory with the same name as a file that has been processed but the modification date remains the same, then that file is not retrieved.

4.3.1.3 File Matching and Batch Processing

The File Filtering page of the Adapter Configuration Wizard shown in Figure 4–21 enables you to specify details about the files to retrieve or ignore. The Oracle File Adapter acts as a file listener in the inbound direction. The Oracle File Adapter polls the specified directory on a local or remote file system and looks for files that match specified naming criteria. 4-38 Oracle Fusion Middleware Users Guide for Technology Adapters Figure 4–21 The Adapter Configuration Wizard-File Filtering Page The following sections describe the file filtering information to specify: ■ Section 4.3.1.3.1, Specifying a Naming Pattern ■ Section 4.3.1.3.2, Including and Excluding Files ■ Section 4.3.1.3.4, Debatching Multiple Inbound Messages

4.3.1.3.1 Specifying a Naming Pattern

Specify the naming convention that the Oracle File Adapter uses to poll for inbound files. You can also specify the naming convention for files you do not want to process. Two naming conventions are available for selection. The Oracle File Adapter matches the files that appear in the inbound directory. ■ File wildcards po.txt Retrieves all files that start with po and end with .txt. This convention conforms to Windows operating system standards. ■ Regular expressions po.\.txt Retrieves all files that start with po and end with .txt. This convention conforms to Java Development Kit JDK regular expression regex constructs. Oracle JCA Adapter for FilesFTP 4-39

4.3.1.3.2 Including and Excluding Files

If you use regular expressions, the values you specify in the Include Files and Exclude Files fields must conform to JDK regular expression regex constructs. For both fields, different regex patterns must be provided separately. The Include Files and Exclude Files fields correspond to the IncludeFiles and ExcludeFiles parameters, respectively, of the inbound WSDL file. If you want the inbound Oracle File Adapter to pick up all file names that start with po and which have the extension txt, then you must specify the Include Files field as po.\.txt when the name pattern is a regular expression. In this regex pattern example: ■ A period . indicates any character. ■ An asterisk indicates any number of occurrences. ■ A backslash followed by a period \. indicates the character period . as indicated with the backslash escape character. The Exclude Files field is constructed similarly. If you have Include Files field and Exclude Files field expressions that have an overlap, then the exclude files expression takes precedence. For example, if Include Files is set to abc.txt and Exclude Files is set to abcd.txt, then you will not receive any abcd.txt files. Notes: ■ If you later select a different naming pattern, ensure that you also change the naming conventions you specify in the Include Files and Exclude Files fields. The Adapter Configuration Wizard does not automatically make this change for you. ■ Do not specify . as the convention for retrieving files. ■ Be aware of any file length restrictions imposed by your operating system. For example, Windows operating system file names cannot be more than 256 characters in length the file name, plus the complete directory path. Some operating systems also have restrictions on the use of specific characters in file names. For example, Windows operating systems do not allow characters such as backslash\, slash , colon :, asterisk , left angle bracket , right angle bracket , or vertical bar|. Note: The regex pattern complies with the JDK regex pattern. According to the JDK regex pattern, the correct connotation for a pattern of any characters with any number of occurrences is a period followed by a plus sign .+. An asterisk in a JDK regex is not a placeholder for a string of any characters with any number of occurrences. Note: You must enter a name pattern in the Include Files with Name Pattern field and not leave it empty. Otherwise, the inbound adapter service reads all the files present in the inbound directory, resulting in incorrect results. 4-40 Oracle Fusion Middleware Users Guide for Technology Adapters Table 4–3 lists details of Java regex constructs. Note: Do not begin JDK regex pattern names with the following characters: plus sign +, question mark ?, or asterisk . Table 4–3 Java Regular Expression Constructs Matches Construct Characters - The character x x The backslash character \\ The character with octal value 0n 0 = n = 7 \0n The character with octal value 0nn 0 = n = 7 \0nn The character with octal value 0mnn 0 = m = 3, 0 = n = 7 \0mnn The character with hexadecimal value 0xhh \xhh The character with hexadecimal value 0xhhhh \uhhhh The tab character \u0009 \t The new line line feed character \u000A \n The carriage-return character \u000D \r The form-feed character \u000C \f The alert bell character \u0007 \a The escape character \u001B \e The control character corresponding to x \cx - - Character classes - a, b, or c simple class [abc] Any character except a, b, or c negation [abc] a through z or A through Z, inclusive range [a-zA-Z] a through d, or m through p: [a-dm-p] union [a-d[m-p]] d, e, or f intersection [a-z[def]] a through z, except for b and c: [ad-z] subtraction [a-z[bc]] a through z, and not m through p: [a-lq-z]subtraction [a-z[m-p]] - - Predefined character classes - Any character may or may not match line terminators - A digit: [0-9] \d A nondigit: [0-9] \D A white space character: [ \t\n\x0B\f\r] \s A nonwhitespace character: [\s] \S A word character: [a-zA-Z_0-9] \w Oracle JCA Adapter for FilesFTP 4-41 For details about Java regex constructs, go to http:java.sun.comj2se1.5.0docsapi

4.3.1.3.3 File Include and Exclude

The FileList operation does not expose the java.file.IncludeFiles property. This property is configured while designing the adapter interaction and cannot be overridden via headers, for example: adapter-config name=ListFiles adapter=File Adapter xmlns=http:platform.integration.oracleblocksadapterfwmetadata connection-factory location=eisFileAdapter UIincludeWildcard=.txt adapterRef= endpoint-interaction portType=FileListing_ptt operation=FileListing interaction-spec className=oracle.tip.adapter.file.outbound.FileListInteractionSpec property name=PhysicalDirectory value=INP_DIR property name=PhysicalDirectory value=INP_DIR property name=Recursive value=true property name=Recursive value=true property name=IncludeFiles value=.\.txt interaction-spec endpoint-interaction adapter-config In this example, IncludeFiles, once set, cannot be changed.

4.3.1.3.4 Debatching Multiple Inbound Messages

You can select whether incoming files have multiple messages, and specify the number of messages in one batch file to publish. When a file contains multiple messages and this check box is selected, this is referred to as debatching. Nondebatching is applied when the file contains only a single message and the check box is not selected. Debatching is supported for native and XML files.

4.3.1.4 File Polling

The File Polling page of the Adapter Configuration Wizard shown in Figure 4–22 enables you to specify the following inbound polling parameters: ■ The frequency with which to poll the inbound directory for new files to retrieve. A nonword character: [\w] \W Greedy quantifiers - X, once or not at all X? X, zero or more times X X, one or more times X+ X, exactly n times X{n} X, at least n times X{n,} X, at least n, but not more than m times X{n,m} Table 4–3 Cont. Java Regular Expression Constructs Matches Construct 4-42 Oracle Fusion Middleware Users Guide for Technology Adapters ■ The minimum file age of files to retrieve. For example, this polling parameter enables a large file to be completely copied into the directory before it is retrieved for processing. The age is determined by the last modified time stamp. For example, if you know that it takes three to four minutes for a file to be written, then set the minimum age to five minutes. If a file is detected in the input directory and its modification time is less than five minutes older than the current time, then the file is not retrieved because it is still potentially being written to. Figure 4–22 The Adapter Configuration Wizard-File Polling Page Using Trigger Files By default, polling by inbound Oracle File and FTP Adapters start as soon as the endpoint is activated. However, if you want more control over polling, then you can use a file-based trigger. Once the Oracle File or FTP Adapter finds the specified trigger file in a local or remote directory, it starts polling for the files in the inbound directory. For example, a BPEL process is writing files to a directory and a second BPEL process is polling the same directory for files. If you want the second process to start polling the directory only after the first process has written all the files, then you can use a trigger file. You can configure the first process to create a trigger file at the end. The second process starts polling the inbound directory once it finds the trigger file. The trigger file directory can be the same as the inbound polling directory or different from the inbound polling directory. However, if your trigger file directory and the inbound polling directory are the same, then you should ensure that the name of the trigger file is not similar to the file filter specified in the Adapter Configuration page shown in Figure 4–21 . The content of a trigger file is never read and therefore should not be used as payload for an inbound receive activity. Note: You must not manually change the value of polling parameters in JCA files. You must use the Adapter Configuration Wizard to modify this parameter. Oracle JCA Adapter for FilesFTP 4-43 Table 4–4 lists the parameters that you must specify in the inbound service JCA file: The following is a sample JCA file for the inbound service: Table 4–4 Trigger File Parameters Parameter Description Example TriggerFilePhysicalDirec tory or TriggerFileLogicalDirect ory The physical or logical name of the directory in which the Oracle File and FTP Adapters look for the trigger file. The TriggerFilePhysicalDi rectory and TriggerFileLogicalDir ectory parameters are optional. These parameters must be used only if the trigger file directory is different from the inbound polling directory. By default, the Oracle File and FTP Adapters looks for the trigger file in the inbound polling directory. TriggerFilePhysicalDi rectory=C:\foo TriggerFileLogicalDir ectory= TriggerFileDir TriggerFile The name of the trigger file. TriggerFile=Purchase order.trg TriggerFileStrategy Strategy that is used as the triggering mechanism. The value can be one of the following: EndpointActivation: The adapter looks for the trigger file every time the composite is activated. Note: The composite gets activated every time you start the container or redeploy the application, or retire or activate the composite application from Oracle Enterprise Manager. Every time you restart the container, the composite application is not triggered until it sees the trigger file in the specified directory. OnceOnly: The adapter looks for the trigger file only once in its lifetime. Once it finds the trigger file, it remember that across restarts and redeployments. EveryTime: The adapter looks for the trigger file on each polling cycle.The default value for TriggerFileStrategy is EndpointActivation. TriggerFileStrategy= EndpointActivation 4-44 Oracle Fusion Middleware Users Guide for Technology Adapters ?xml version=1.0 encoding=UTF-8? adapter-config name=FlatStructureIn adapter=File Adapter xmlns=http:platform.integration.oracleblocksadapterfwmetadata connection-factory location=eisFileAdapter UIincludeWildcard=.txt adapterRef= endpoint-activation operation=Read activation-spec className=oracle.tip.adapter.file.inbound.FileActivationSpec property... property name=TriggerFilePhysicalDirectory value=tmpflatArchiveDir activation-spec endpoint-activation adapter-config

4.3.1.5 Postprocessing

The Oracle File Adapter supports several postprocessing options. After processing the file, files are deleted if specified in the File Polling page shown in Figure 4–22 . Files can also be moved to a completion archive directory if specified in the File Directories page shown in Figure 4–20 .

4.3.1.6 Native Data Translation

The next Adapter Configuration Wizard page that appears is the Messages page shown in Figure 4–23 . This page enables you to select the XSD schema file for translation. Figure 4–23 Specifying the Schema - Messages Page If native format translation is not required for example, a JPG or GIF image is being processed, then select the Native format translation is not required check box. The file is passed through in base-64 encoding. Oracle JCA Adapter for FilesFTP 4-45 XSD files are required for translation. If you want to define a new schema or convert an existing data type definition DTD or COBOL Copybook, then select Define Schema for Native Format . This starts the Native Format Builder wizard. This wizard guides you through the creation of a native schema file from file formats such as comma-separated value CSV, fixed-length, DTD, and COBOL Copybook. After the native schema file is created, the Messages page is displayed, with the Schema File URL and Schema Element fields filled in. For more information, see Section 6.1, Creating Native Schema Files with the Native Format Builder Wizard.

4.3.1.7 Inbound Service

When you finish configuring the Oracle File Adapter, a JCA file is generated for the inbound service. The file is named after the service name you specified on the Service Name page of the Adapter Configuration Wizard. You can rerun the wizard later to change your operation definitions. The ActivationSpec parameter holds the inbound configuration information. The ActivationSpec and a set of inbound Oracle File Adapter properties are part of the inbound JCA file. Table 4–5 lists the properties of a sample inbound JCA file. The ActivationSpec property values are specified in the Adapter Configuration Wizard during design time and, as shown in Table 4–5 . The inbound Oracle File Adapter uses the following configuration properties: ■ PollingFrequency ■ MinimumAge ■ PhysicalDirectory ■ LogicalDirectory ■ PublishSize ■ PhysicalArchiveDirectory ■ LogicalArchiveDirectory ■ IncludeFiles Note: Ensure that the schema you specify includes a namespace. If your schema does not have a namespace, then an error message is displayed. Table 4–5 Sample JCA Properties for Inbound Service Property Sample Value UseHeaders true PhysicalDirectory tmpopaquein Recursive true DeleteFile false IncludeFiles .\.xml PollingFrequency 1 MinimumAge