How the connector works

The JText connector communicates with an application through the exchange of text or binary files. It performs the following primary tasks when processing business objects:

This section describes these tasks. It also explains how data handler processing works and how the JText connector processes verbs.

Event notification

The JText connector handles events differently from other connectors. Unlike connectors that depend on third-party applications, the JText connector does not have an event table. Instead, it treats the event directory as an event table.

The following operations occur when the JText connector handles events:

  1. The connector polls for events by checking specified directories for files with specified extensions. The presence of a file with the specified extension in the specified directory is considered the equivalent of an event. The connector reads event files directly from the event directory without interpretation. It uses a parsing method to determine which subsection represents each business object. For more information, see Polling for specific business objects.
  2. The connector creates an instance of the data handler (based on values specified in the JText meta-object for the data business object).
  3. The connector calls getBO()or getBOByteArray() on the data handler instance, and sends the string or byte array that represents the business object to it. The connector passes each element that represents a business object to the data handler. When a file represents multiple business objects, the connector sends only an element (that is, a string or byte array representation of a single business object), not the entire file.
  4. The data handler converts the string or byte array to a business object and returns it to the connector. The data handler also reports errors and provides tracing.
  5. The data handler performs default verb processing. The person who develops the data handler must specify logic for setting the verbs, because the connector does not provide this logic. For information on how the sample data handlers set verbs, see the Data Handler Guide.
  6. If the data handler encounters any error that prevents it from creating a business object, the connector archives the string or byte array with the.fail extension. If the data handler succeeds, the connector checks for subscriptions to the business object.
  7. If the connector successfully sends the business object to the integration broker, it archives the file with the .success or .partial extension, depending on whether any business object in the event file has failed processing. If the connector fails to send the business object, it archives the file with the .fail extension.

Depending on its configuration, the JText connector can pick up all files in the event directory or pick up only those with a specified extension. For more information, see Specifying multiple event files or multiple event directories.

The JText connector processes event files in the order of their time stamps, from the oldest to the most recent, regardless of their location. In other words, the JText connector processes files located in separate directories in the chronological order of their time stamps.

The PollQuantity property specifies the maximum number of business objects that the connector can post to the integration broker in a given poll. For example, assume that the value of PollQuantity is set to 5 and that there are two files in a directory in which the connector is polling. The first file has four business objects and the second has 12 business objects. On the first poll call, the connector performs the following steps:

  1. Sends all four business objects from the first file, archiving each business object as it processes it.
  2. Sends the first business object from the second file.

On the second poll call, the connector sends the 2nd through 6th business objects from the second file. On the third poll call, the connector sends the 7th through 11th business objects from the second file. On the fourth poll, the connector sends the last business object. The connector archives each business object after processing it. If any of the business objects in a file fail processing, the connector archives the entire file with the .orig extension.

For more information, see:

Figure 3 shows an event notification operation (numbers in the graphic do not correlate to the steps outlined above).

Figure 3. Event notification operation

Event archiving

After it has processed an event, and if it is configured to enable archiving, the JText connector writes the business object string or byte array representation of one business object into a file in the local archive directory. It names the file with an underscore (_), a time stamp, and a file extension that corresponds to the event status. The delivered default extensions are success, partial, unsub, orig, and fail. The underscore and time stamp are appended after the filename and before the file extension.

The time stamp is an underscore-separated list that contains the year, month, day, hour, minute, second, and millisecond of the system time. It ensures that archived filenames are unique and that the connector does not overwrite an existing file with the same name. The format of the archived file is:

BOName_YYYY_MM_DD_HH_MM_SS_sss.[extension]
 

For example, the connector might rename a successfully processed file named Customer.in to Customer_2003_11_15_18_24_59_999.success.

The JText connector archives a business object to the .fail file if a formatting error occurs, or if the connector fails to send the business object to the integration broker. The JText connector archives a business object to a file with an extension of .unsub if the connector does not subscribe to it. After you examine these archive files and correct any formatting errors or start the processes that subscribe to the business objects, resubmit the business objects in these files for processing.

For more information on archiving, see Specifying event archiving.

Default file extensions for event and archive files

Because the JText connector does not use event and archive tables, it updates event status by changing file extensions. Table 1 shows the default file extension values that the Adapter for JText delivers for event and archive files.

Table 1. Default file extensions

File type Event status/description Default file extension Delivered default directory
Event new
in
 
C:\temp\JTextConn\Default\Event
Archive success (if all the business objects in the event file process successfully, this file contains all the business objects)
success
 
C:\temp\JTextConn\Default\Archive
Archive success (if some of the business objects in the event file fail processing, this file contains only the successfully processed ones)
partial
 

C:\temp\JTextConn\Default\Archive
Archive unsubscribed
unsub
 
C:\temp\JTextConn\Default\Archive
Archive entire original event file (created only if any business object fails processing or is unsubscribed, even if the event file contains only one business object)
orig
 
C:\temp\JTextConn\Default\Archive
Archive fail
fail
 
C:\temp\JTextConn\Default\Archive
Output out
out
 
C:\temp\JTextConn\Default\Out
Important:
The access sequence among multiple applications that access and process the same file at the same time is important. Analyze all operations performed on a given file to avoid issues with file locking and incomplete data.
Note:
The connector treats every file in the event directory with the specified extension as an input file. Ensure that the input file extension differs from the archive file extension, or that the input files and archive files are stored in different directories, to prevent the connector from treating an archived file as an event.

For information on specifying your own file extensions, event directory, and output directory, see Table 8..

Request processing

When processing a service call request, the connector converts the business object to an output string or byte array, then writes it to a file.

Before converting the business object, however, the connector determines whether the business object has been configured for dynamic file naming; that is, whether the business object contains a dynamic child meta-object. In this case, the connector dynamically names the output file or returns the name of the output file that it generates.

This section describes service call request processing when:

Data business object does not specify dynamic file naming

When the data business object does not specify dynamic file naming, the connector performs the following operations to handle service call requests:

  1. The connector receives a business object request.
  2. The connector determines that the AppSpecificInfo property at the business-object level must contain the following:
    cw_mo_JTextConfig = DynChildMOAttrName
     
    
  3. The connector checks the configuration of the top-level JText meta-object to determine which data handler to call. By default, this meta-object specifies the MO_DataHandler_DefaultNameValueConfig data-handler meta-object, which represents the NameValue data handler.
  4. The connector creates an instance of the appropriate data handler and sends the business object to it.
  5. The data handler converts the business object to a string or a byte array, which it returns to the configuration. The data handler also reports errors and provides tracing.
  6. The connector writes the string or byte array to a file.

For information on configuring the connector to process requests, see Specifying request processing.

Data business object contains a dynamic child meta-object

When the data business object contains a dynamic child meta-object, the connector performs the following operations to handle service call requests:

  1. The connector receives a business object request.
  2. The connector determines that the AppSpecificInfo property at the business-object level contains the following text:
    cw_mo_JTextConfig = DynChildMOAttrName
     
    
    Note:
    If the business object's application-specific information does not specify a dynamic child meta-object and does not contain such a child, the connector processes the business object as described in "Data business object does not specify dynamic file naming".
  3. The connector gets the name of the output file from the dynamic child meta-object's OutFileName attribute.
  4. The connector checks the configuration of the top-level JText meta-object to determine which data handler to call. By default, this meta-object specifies the MO_DataHandler_DefaultNameValueConfig data-handler meta-object, which represents the NameValue data handler.
  5. The connector creates an instance of the appropriate data handler and sends the business object to it.
  6. The data handler converts the business object to a string or a byte array, which it returns to the configuration. The data handler also reports errors and provides tracing.
  7. The connector writes the string or byte array to a file whose name it derives in step 3. above.

Figure 4 illustrates the JText connector components when the connector processes requests from an integration broker to the destination application.

Figure 4. Business object request operation

How data handler processing works

The connector uses a data handler instance to convert between business objects and strings or byte arrays that are read from event files. The data handler instance also reports errors and provides tracing.

The connector creates an instance of a data handler based on the value of the EventDataHandler and OutputDataHandler attributes in the top-level JText meta-object. These attributes identify the data-handler meta-object that the connector uses to create the instance of the data handler. The data-handler meta-object can represent a delivered or custom data handler. For more information, see the Data Handler Guide.

The connector determines which interface, string or byte array, based on the setting of the DataProcessingMode meta-object. For additional information on this meta-object, see Table 8

After receiving the configuration information, the connector performs the following steps:

  1. Instantiates a data handler.
  2. Calls the data handler's setOption() method to set the data handler's TracingSubSystem attribute to the connector's name. The data handler uses this value to include the connector's name in the trace messages it writes.

After the data handler has been created and configured, the connector calls the appropriate methods in the data handler to perform the conversion of data to or from a business object.

The getBO(String) or getBO(byte[])and the getStringFromBO() or getByte ArrayFromBO() methods always send or receive the entire business object hierarchy of a top-level parent and all of its child business objects, respectively.

In either case, the data handler is responsible for filtering out any meta-object data so that it passes only business object-specific data. The product-delivered data handlers provide this functionality. If you use custom data handlers, they must also provide this functionality.

Business object verb processing for requests

When handling requests, the JText connector does not handle one verb differently from another. It writes to files without performing update, retrieve, or delete operations, regardless of the verb associated with the business object.

When processing requests, the JText connector sets all attributes with a value of CxIgnore to their default values if the following conditions are true:

Copyright IBM Corp. 2003