{scrollbar}

File Binding Example

Overview

This document describes how to run ServiceMix's File Binding example and provides details about what it does. For information on the business use case, please refer to the last section: use case.

The File Binding example illustrates the following:

The XML code for the File Binding example is located in the ServiceMix installation directory under the examples\file-binding directory in the servicemix.xml file. It is recommended that you refer to the servicemix.xml file while reading this document.

The File Binding XML file, servicemix.xml, contains two components and a supporting bean. One component waits for a file to be deposited into the the inboxdirectory, retrieves it, creates a normalized message that contains the file, then sends the message to the Normalized Message Router (NMR). The NMR routes the file to the other component, which deposits it into an outbox directory. Please be aware that for the out-of-the-box example the input and output files are not necessarily binary identical as their XML DOM is processed; so for instance comments will be lost. The bean provides a thread pool to enhance the performance of the reading and processing of the files. Details about the components and bean are discussed below.

Note

The file to be transmitted from the inbox to outbox must be in XML format.

Running the File Binding Example

From a command shell, go to the File Binding example directory:

cd [SM30UG:servicemix_install_dir]\examples\file-binding

where servicemix_install_dir is the directory in which ServiceMix was installed.

Before running the example, copy a test file into the inbox directory:

copy test-file.xml inbox

You need to download additional jars by running:

ant setup

Then type:

[SM30UG:servicemix_install_dir]\bin\servicemix servicemix.xml OR ..\..\bin\servicemix servicemix.xml


After a few seconds, the sample_xxx.xml file will appear in the outbox directory. To see this open another command window and do a directory listing on the outbox directory, for example:

dir [SM30UG:servicemix_install_dir]\examples\file-binding\outbox

If you would like to see more files moved from inbox to outbox, copy another file into the inbox directory. The file binding program continually polls (every 1000 ms) for new files, so any new file placed in inbox, will be transmitted to outbox.

Handy Hint

Add $SERVICEMIX_HOME/bin directory to $PATH variable to simplify execution of the example.

Stopping the File Binding Example

To terminate the File Binding example type "CTRL-C" in the command shell in which it is running and answer "y" to the "Terminate batch job (y/n)?" question.

How it Works

The diagram below illustrates the logical flow of the program through the file binding components.



#cccFile Binding Logical Flow Diagramsolid



The logical flow of the program is:

  1. The filePoller polls the inbox directory every 1000 ms looking for a file.
  2. Once a file appears in the inbox directory, the filePoller gets a thread from the workManager. The thread will be used to process the file.
  3. The filePollercreates a normalized message that contains the file to be transmitted. It sends the normalized message to the NMR. The NMR routes the message to the fileSender component.
  4. The fileSender transforms the normalized message back into a file and "sends" it (places it) to the outbox directory.

Logging information is written to the console as files are transmitted. Typical output looks like the following:

Starting Apache ServiceMix ESB: 3.0-incubating Loading Apache ServiceMix from file: servicemix.xml INFO - JBIContainer - ServiceMix 3.0-incubating JBI Container (ServiceMix) is starting INFO - JBIContainer - For help or more informations please see: http://incubator.apache.org/servicemix/ INFO - ConnectorServerFactoryBean - JMX connector available at: service:jmx:rmi:///jndi/rmi://localhost:1099/jmxrmi INFO - ComponentMBeanImpl - Initializing component: #SubscriptionManager# INFO - DeploymentService - Restoring service assemblies INFO - ComponentMBeanImpl - Initializing component: fileSender INFO - ComponentMBeanImpl - Initializing component: filePoller INFO - JBIContainer - ServiceMix JBI Container (ServiceMix) started

Details

The following table provides more details about the function of each component and bean in the servicemix.xml file.

Component or Bean ID

Description

filePoller

This component periodically checks the "inbox" directory looking for files. If there is a file or directory present, it adds the file to the "workingSet", which is a collection of files to be processed. The workManger is invoked to schedule the work of processing the file from the workingSet. Another thread is created and the processing of the file begins. Processing consists of marshalling the file (streaming it from disk into a normalized message). The normalized message is sent over the NMR to the fileSender component per the specified "destinationService". The destinationService is specified in the servicemix.xml file as an attribute the filePoller component. In this example, the "destinationService" is the fileSender component. Finally, after it has been processed, the filePoller deletes the file from the source directory.

fileSender

This component is the "destinationService" for the filePoller. It receives normalized messages from filePoller. The messages it receives are the files that filePollerhas transferred to it via the NMR. It converts the normalized message to its original file format and sends it to the destination directory, the outbox directory. This component creates the filename to which to copy the file by concatenating the string "sample_" with the process id following by ".xml". The concatenated string is passed to the org.servicemix.expression.JaxenStringXPathExpression bean as an argument to the constructor, as can be seen by the constructor-arg value tag in the XML file.

workManager

This bean is used by the filePoller to increase the throughput of the application. The workManager is a thread pool whose size can be adjusted declaratively in the servicemix.xml file. The other components in the File Binding application ask the workManager for threads as needed. For example, threads are used by this application to periodically (every second) check for files in the inbox. Other threads are used to do the work of processing files (streaming them in, normalizing them, and sending them to the NMR). Note: The fileSender component also uses a thread to do its' work, however, it is not using a thread from the workManager's thread pool.

Useful Code Hints

This section describes the start-up sequence and how the ServiceMix container interacts with the File Bindingapplication. The Java class files are located in the servicemix-1.0.1.jar file in the ServiceMix installation directory. To look at the Java source code, unjar and decompile the .class files or download the source code. Please note: the downloadable source code is slightly different than the compiled binary code.

Viewing the Java source code is recommended for understanding the information in this section.

filePoller Details

  1. The ServiceMix container reads the servicemix.xml file and sees it needs to instantiate a FilePoller.
  2. The container calls the init() method of FilePoller, as well as the init() methods of its parents.
  3. The container determines that FilePoller is an MBean and, therefore, calls the start() method of FilePoller, which it inherits from its parent PollingComponentSupport.
  4. The start() method will: (See: PollingComponentSupport.java code fragment below)
    A. Create a timerTask.
    B. Schedule the timerTask at a fixed rate. The start() method uses the "timer" (created in the init method) to schedule the timerTask at a fixed rate: timer.scheduleAtFixedRate(timerTask, firstTime, period). Recall "period" is a property of FilePoller. It was assigned the value of 1000ms by dependency injection from the servicemix.xml file.
    C. timer will call the run() method of the timerTask periodically. timerTask's run method() is defined inline. This run() method will get the workManager object (see below for details).
    D. The workManager will call "scheduleWork(PollingComponentSupport.this)". _Note:_it passes in PollingComponent support, which by virtue of its inheritance hierarchy, is of type "Work", which is a "Runnable" object.
    E. "workManager.scheduleWork(Work)" will get a Thread, passing in a Runnable object, i.e. PollingComponentSupport, and call its run() method.
    F. PollingComponent's run() method calls poll(), which is implemented in FilePoller.
    G. From this point on the call sequence can be followed in FilePoller...
    H. The start() method of PollingComponentSupport, will eventually call super.start(), which propagates up to call the start() method of BaseLifeCycle, which sets the component state to "RUNNING."

Eventually, one of the threads that is polling (see step G) for a file in the inbox directory will see a one. It will use workManager's thread pool to get a thread for processing the file. Processing the file consists of streaming it from inbox, creating a normalized message, and sending the message to the NMR.

PollingComponentSupport.javasolid protected void init() throws JBIException { if (scheduler == null) { scheduler = new Scheduler(true); } if (scheduleIterator == null) { scheduleIterator = new PollScheduleIterator(); } if (workManager == null) { ComponentContextImpl context = (ComponentContextImpl) getContext(); workManager = context.getWorkManager(); } super.init(); }

workManager Details

workManager is a property of the FilePoller object. This property is defined by a local reference, the "ref" attribute in the servicemix.xml file. The local reference is a bean which instantiates org.activemq.work.SpringWorkManager.

The SpringWorkManager is a Spring bean. By default when a Spring bean starts, the properties are set, and then the afterPropertiesSet() method is called by the container.

The workManager is used to allocate threads. The FilePoller asks for threads from the workManager for two operations:

  1. The timerTask uses threads from the thread pool to periodically check the inbox directory for files.
  2. The workManager will also allocate a thread to process a file (read, normalize and send to NMR). The workManager calls a scheduleWork() method which is non-blocking. Therefore, if multiple files need to be processed, FilePoller can continue making requests to the workManager to schedule work.

Summarizing, when the ServiceMix container instantiates an MBean it firsts sets the property values if there are any, then calls the init() method of the class and its' parent classes, if applicable. Then it calls the start() method of the class. When a Spring bean starts up, the properties are set and then the afterPropertiesSet() method is called.

Use case

The file binding example shows how components of ServiceMix can interact with the file system. This is important because there are applications that write files out to a directory on disk and other applications that may need access to those files. This is a simple example of how a ServiceMix component can read a file from the disk, process it into a normalized message, then send it via the NMR to another ServiceMix component. The receiving component can process the message (which contains the file) and write it out to another location on disk.

A hypothetical business scenario: An online wholesale distributor of books and music CDs, receives a nightly order from a retail store. The nightly order is transmitted to the distributor as a file and placed in a particular directory on disk. There is a ServiceMix component (getOrders) that continually scans that directory looking for order files. When it sees a file, it reads it from the disk, then transforms it into a normalized message. It sends the message over the bus (NMR) to another component called "placeOrders." The placeOrders program divides the order into separate orders for its' suppliers, e.g., one order will be placed with the distributor's book supplier, one order will go to the CD supplier, etc. At some later point, the suppliers will log in and retrieve their order files - this is not shown here, but can have an automatic or manual implementation and this process could also be integrated with ServiceMix.

The following diagram illustrates this:

#cccOnline Distributor's Order Processing Systemsolid

Related Documentation

For more information on the following topics please see:


For a brief explanation of the XML tags in the servicemix.xml file, please see:

{scrollbar}