This page summarizes the different types and complexity levels of integration of components in SMILA.

+

This page summarizes the different types and complexity levels for the integration of components in SMILA.

+

== Introduction ==

−

== Integration of Services in BPEL ==

+

Due to its architecture SMILA allows for the easy integration of third-party components into its framework. Actually there are four different possible integration scenarios available that are depicted in the following table.

−

There are several options on how to integrate new functionality in SMILA BPEL workflows (called [[SMILA/Glossary#P|Pipelines]]).

+

{| class="wikitable" border="1" cellpadding="5"

+

|-

+

| [[#Integrating a SMILA pipelet|Integrating a SMILA pipelet]]

+

|-valign="top"

+

| This is probably the most frequently used integration scenario. It allows for the integration or exchange of functionality (services, 3rd party software, etc.) used to process records in the workflow engine.

+

|-valign="top"

+

| [[image:Integrate-Service_1.1.0.png|900px]]

+

|-valign="top"

+

| The figure demonstrates how you can integrate the functionality of your service or your piece of software to SMILA by adding it to the workflow engine.

+

|}

−

==== Simple: webservices ====

−

The simplest way of integrating additional functionality in SMILA is to call a webservice. This is a standard BPEL workflow engine functionality independent of SMILA. There are some limitations concerning the input und result data to/from webservices. [[SMILA/Glossary#R|Records]] are NOT accessible from a BPEL workflow! It is only possible to use the values contained in the BPEL workflow object. By default the workflow object contains only the [[SMILA/Glossary#I|ID]] of a [[SMILA/Glossary#R|Record]]. Though it is possible to include [[SMILA/Glossary#A|Attributes]] and [[SMILA/Glossary#A|Annotations]] of [[SMILA/Glossary#R|Records]] in the workflow object, [[SMILA/Glossary#A|Attachments]] are not supported. The content of the workflow object can be configured by filters in the configuration file <tt>org.eclipse.eilf.blackboard/RecordFilters.xml</tt>. You need to include [[SMILA/Glossary#A|Attributes]]/[[SMILA/Glossary#A|Attachments]] used for input as well as for output.

−

'''Examples''':

+

{| class="wikitable" border="1" cellpadding="5"

−

* A good example for this use case is the integration of [[http://www.languageweaver.com/home.asp Language Weaver]]. The Language Weaver Translation Server provides a webservice interface that allows a text to be translated into another language. This service could be easily used within SMILA.

+

|-

+

| [[#Integrating workers|Integrating workers]]

+

|-valign="top"

+

| Integrating your own [[SMILA/Glossary#W|worker]] implementation is another common scenario for adding functionality or adapting workflows to SMILA.

+

|-valign="top"

+

| [[image:Integrate-Worker_1.1.0.png|900px]]

+

|-valign="top"

+

| The figure above exemplary shows how you can add your own worker implementation to SMILA. Please note that you also have to add the worker to the job manager configuration files (workers.json, workflows.json) and add your worker as an OSGi service to activate it.

+

|}

−

Here are more detailed technical descriptions:

−

* How to integrate a webservice in a SMILA BPEL pipeline

+

{| class="wikitable" border="1" cellpadding="5"

+

|-

+

| [[#Integrating data sources|Integrating data sources]]

+

|-valign="top"

+

| Integrating a data source by implementing your own crawler is another scenario for adding functionality to SMILA. By doing so, further data sources can be unlocked to provide additional input to SMILA.

+

|-valign="top"

+

| [[image:Integrate-DataSources_1.1.0.png|900px]]

+

|-valign="top"

+

| The figure above exemplary shows how you can add your own crawler implementation to SMILA. Please note that eventually you have to add a new Fetcher or extractors or further workers as well and you also have to add a new workflow definition, which is not shown in the figure. This was chosen due to simplicity.

+

|}

−

==== Default: local SMILA Pipelet or ProcessingService ====

−

The default technique to integrate functionality or software in SMILA is to write a [[SMILA/Glossary#P|Pipelet]] or [[SMILA/Glossary#P|ProcessingService]] that runs in the same OSGi runtime as the BPEL workflow engine. [[SMILA/Glossary#P|Pipelets]] are easier to implement than [[SMILA/Glossary#P|ProcessingServices]]. For more information about [[SMILA/Glossary#P|Pipelets]] and [[SMILA/Glossary#P|ProcessingServices]] see [[SMILA/Documentation/Pipelets_and_ProcessingServices|Pipelets_and_ProcessingServices]].

−

Both [[SMILA/Glossary#P|Pipelets]] and [[SMILA/Glossary#P|ProcessingServices]] have full access to the [[SMILA/Glossary#R|Records]] in SMILA via the [[SMILA/Glossary#B|BlackboardService]]. So it's easily possible to read, modify and store [[SMILA/Glossary#R|Records]]. In general [[SMILA/Glossary#P|Pipelets]] and [[SMILA/Glossary#P|ProcessingServices]] follow the same (sometimes optional) logical steps (of course this depends highly on the business logic to be executed). These steps are:

−

* read the configuration (optional)

−

* read input data from [[SMILA/Glossary#B|Blackboard]] (optional)

−

* execute the business logic

−

* write result data to [[SMILA/Glossary#B|Blackboard]] (optional)

−

In the part of your [[SMILA/Glossary#P|Pipelet]]/Processing service that implements the business logic you are totally free to use any desired technology. Some of the posibilities include

+

{| class="wikitable" border="1" cellpadding="5"

−

* use of POJOs (e.g. see the various [[SMILA/Documentation/Bundle_org.eclipse.eilf.processing.pipelets.xmlprocessing|XML Processing Pipelets]])

+

|-

−

* use any local available OSGi service, even other [[SMILA/Glossary#P|ProcessingServices]] (e.g. see the [[SMILA/Documentation/AperturePipelet|AperturePipelet]] that uses the [[SMILA/Documentation/ApertureMimeTypeIdentifier|ApertureMimeTypeIdentifier]])

* use other technologies like JNI, RMI, Corba, etc. to integrate remote or non Java components (e.g. integration of Oracle Outside In Technology)

+

|-valign="top"

−

* ...

+

| This scenario is particularly intended for the experienced (SMILA) developer and comprises the possibility to exchange existing implementations of the SMILA core components by your own implementations.

+

|-valign="top"

+

| [[image:Provide-Alternative-To-Core-Component_1.1.0.png|900px]]

+

|-valign="top"

+

| The figure above demonstrates one of the SMILA core components -- ''data store'' -- may be exchanged by your own implementation. This serves as examples only, that is, you may also exchange other core components such as the [[SMILA/Glossary#B|blackboard service]].

+

|}

+

{{Note|The above figures exemplary demonstrate at which levels in the [http://www.eclipse.org/smila SMILA architecture] an integration of new components is applicable. However, for simplicity reason, we restricted the above figures to the index processing chain while completely ignoring the search processing chain that offers the same integration options (except for the integration of agents and crawlers), but is currently not in the focus of this page.

+

}}

−

'''Examples''':

+

== Conventions ==

−

* Typical examples for [[SMILA/Glossary#P|Pipelets]] are the [[SMILA/Documentation/Bundle_org.eclipse.eilf.processing.pipelets.xmlprocessing|XML Processing Pipelets]]. These lightweight [[SMILA/Glossary#P|Pipelets]] are used for XML processing (e.g. XSL transformation). Each [[SMILA/Glossary#P|Pipeline]] uses it's own [[SMILA/Glossary#P|Pipelet]] instance.

+

−

* A good example for a [[SMILA/Glossary#P|ProcessingService]] is the [[SMILA/Documentation/LuceneIndexService|LuceneIndexService]]. It provides functionality to index [[SMILA/Glossary#R|Records]] in Lucene indexes and can be used from multiple [[SMILA/Glossary#P|Pipelines]] in parallel.

+

−

Here are more detailed technical descriptions:

+

=== Handling of Character Encoding ===

−

* [[SMILA/Development_Guidelines/How to write a Pipelet|How to write a Pipelet]]

+

−

* [[SMILA/Development_Guidelines/How to write a ProcessingService|How to write a ProcessingService]]

+

−

==== Advanced: remote SMILA ProcessingService ====

+

To make processing of data in SMILA easier: If external data must be converted to a string (e.g. an attribute value), the crawler/fetcher or any other component accessing an external data source should try everything that is possible to ensure that the conversion is done using the correct encoding. For example, HTTP clients should use the encoding reported by the HTTP server. If the data source does not provide information about the character encoding, you can use the class <tt>org.eclipse.smila.utils.file.EncodingHelper</tt> that tries to convert a byte[] to a string by trying to detect the correct encoding from a <tt>byte[]</tt> by checking BOMs or checking XML and HTML content for instructions and finally by using UTF-8 or, if this fails, the default platform encoding. You may find this helpful.

−

tbd.

+

+

On the other hand, if valid string data must be converted to a byte[] (e.g. if it is stored as a attachment after pipelet processing), the conversion must always use UTF-8 encoding.

+

== Integrating a SMILA pipelet ==

−

== Integration of Agents and Crawlers ==

+

As already shown in the overview above, SMILA offers the possibility to integrate your own service or piece of software into SMILA [[SMILA/Glossary#BPEL|BPEL]] workflows.

+

In SMILA we simply call these workflows [[SMILA/Glossary#P|pipelines]]. A pipeline is the definition of a BPEL process (or workflow) that orchestrates [[SMILA/Glossary#P|pipelets]] and other BPEL services (e.g. web services).

The default and thus recommended technique to integrate simple and small functionality or software in SMILA is to provide a [[SMILA/Glossary#P|pipelet]]. Pipelets are easy to implement as they require only standard Java knowledge. They are not shared between multiple pipelines, even multiple invocations of a Pipelet in the same Pipeline do not share the same instance. The lifecycle and configuration of pipelets is managed by the workflow engine, not by OSGi runtime. Pipelets have full access to SMILA [[SMILA/Glossary#R|records]] by using the [[SMILA/Glossary#B|blackboard service]], which makes it easy to read, modify, and store [[SMILA/Glossary#R|records]]. For further information on pipelets refer to the [[SMILA/Documentation/Pipelets|Pipelets documentation]].

−

* How to implement an Agent

+

In general pipelets follow the same (sometimes optional) logical steps (of course this depends highly on the business logic to be executed). These steps are:

−

* [[SMILA/Development_Guidelines/How to implement a Crawler|How to implement a Crawler]]

+

* Read the configuration (optional)

+

* Read input data from blackboard (optional)

+

* Execute the business logic

+

* Write result data to blackboard (optional)

+

In terms of the pipelet that implements the business logic you are totally free to use any desired technology. Some of the posibilities include:

* Using any local available OSGi service (For an example refer to the [[SMILA/Documentation/Bundle org.eclipse.smila.processing.pipelets#org.eclipse.smila.processing.pipelets.MimeTypeIdentifyPipelet|MimeTypeIdentifyPipelet]] which uses a MimeTypeIdentifier service)

+

* Using other technologies such as JNI, RMI, or CORBA to integrate remote or non Java components.

−

== Providing alternative implementations for SMILA Core-Components ==

+

===== Examples =====

−

SMILa's component based architecture even allows you to provide your own implementations of SMILA core components.

+

* Typical examples for pipelets are the [[SMILA/Documentation/Bundle org.eclipse.smila.processing.pipelets.xmlprocessing|XML processing pipelets]]. These lightweight pipelets are used for XML processing (e.g. XSL transformation). Each pipeline uses its own [[SMILA/Glossary#P|pipelet]] instance.

−

More info comming soon ...

+

−

'''Examples''':

+

===== Further reading =====

−

* a typical example is an alternative implementation of the DeltaIndexingManager that does not store it's state in memory but in the filesystem or in a database

+

Please consult the following how-to tutorials for a more detailed technical description:

+

* [[SMILA/Development_Guidelines/How to write a Pipelet|How to write a pipelet]]

+

* [[SMILA/Development_Guidelines/How to integrate the HelloWorld webservice as a Pipelet|How to integrate the HelloWorld '''web service''' as a pipelet]]

+

== Integrating own workers ==

+

+

When the desired changes to the functionality are not simple and small or the desired functionality requires more than just accessing the records, it is recommended to integrate your functionality as new [[SMILA/Glossary#W|workers]].

+

These workers have to be defined in the asynchronous job processing configuration and can then be integrated in workflows.

+

+

=== Description ===

+

A worker is an OSGi service, that implements the Worker interface, i.e. provides a name (to collect tasks and to be identified in workflows) and offers a threadsafe <tt>perform</tt> method, which takes a <tt>TaskContext</tt> object (generated by the WorkerManager) as an argument.

+

+

Normally the worker will handle a bulk of records in the perform method, manipulate the contained records, may access external services or stores and create new bulks of records.

+

+

The worker does not have to handle tasks or check if tasks are available. These menial tasks are done by the WorkerManager that cares for all registered workers, handles the invocations of their perform methods and copes with input and output bulks, up-scaling or exception handling. The worker just has to provide the perfom method to deal with the records.

+

+

If the worker requires direct access to the JobManager/TaskManager, e.g. because it is an initial worker and has to get initial tasks to start workflow runs without being triggered by previous workers, it must not register itself as a Worker service but has to tackle TaskManager and JobManager itself. Be careful, this is tedious work! So if possible stick to the Worker interface and let everything else be handled by the WorkerManager.

+

+

=== Further reading ===

+

Please consult at least the following pages about asynchronous job processing:

* [[SMILA/Development_Guidelines/How_to_write_a_Worker|How to write a '''worker''']]

+

+

== Integrating data sources ==

+

+

If you like to integrate data sources, you should do so by writing a new Importing-Wokrflow along with apropriate crawler/fetcher workers (and eventually an extractor worker) as is described in [[SMILA/Documentation/HowTo/How_to_add_a_new_Data_Source_to_the_importing_framework|HowTo add a new Data Source to the Importing Framework]].

+

+

This also involves integration of own workers (see [[#Integrating own workers|Integrating own workers]] above).

+

+

=== Further reading ===

+

Please consult the following how-to tutorials for a more detailed technical description:

+

* [[SMILA/Documentation/HowTo/How_to_add_a_new_Data_Source_to_the_importing_framework|HowTo add a new Data Source to the Importing Framework]]

The component-based architecture of SMILA even allows you to provide your own implementations of SMILA core components, since these are implemented as OSGi service components (see [[SMILA/Development_Guidelines/Declarative_Services|Declarativ Services]]) and can thus be exchanged in a standard way.

+

* Include a new plug-in that exposes a service implementing the interface of the core component (e.g. <tt>ObjectStoreService</tt>)

+

* modify the config.ini configuration file in SMILA.application to include and start the new plug-in instead of the plug-in provided by SMILA core.

+

* build your application and run it.

+

+

=== Examples ===

+

+

A typical example could be an alternative implementation of the <tt>ObjectStoreService</tt> that does not store the objects in the file system but in memory or in a database.

Introduction

Due to its architecture SMILA allows for the easy integration of third-party components into its framework. Actually there are four different possible integration scenarios available that are depicted in the following table.

This is probably the most frequently used integration scenario. It allows for the integration or exchange of functionality (services, 3rd party software, etc.) used to process records in the workflow engine.

The figure demonstrates how you can integrate the functionality of your service or your piece of software to SMILA by adding it to the workflow engine.

Integrating your own worker implementation is another common scenario for adding functionality or adapting workflows to SMILA.

The figure above exemplary shows how you can add your own worker implementation to SMILA. Please note that you also have to add the worker to the job manager configuration files (workers.json, workflows.json) and add your worker as an OSGi service to activate it.

Integrating a data source by implementing your own crawler is another scenario for adding functionality to SMILA. By doing so, further data sources can be unlocked to provide additional input to SMILA.

The figure above exemplary shows how you can add your own crawler implementation to SMILA. Please note that eventually you have to add a new Fetcher or extractors or further workers as well and you also have to add a new workflow definition, which is not shown in the figure. This was chosen due to simplicity.

This scenario is particularly intended for the experienced (SMILA) developer and comprises the possibility to exchange existing implementations of the SMILA core components by your own implementations.

The figure above demonstrates one of the SMILA core components -- data store -- may be exchanged by your own implementation. This serves as examples only, that is, you may also exchange other core components such as the blackboard service.

The above figures exemplary demonstrate at which levels in the SMILA architecture an integration of new components is applicable. However, for simplicity reason, we restricted the above figures to the index processing chain while completely ignoring the search processing chain that offers the same integration options (except for the integration of agents and crawlers), but is currently not in the focus of this page.

Conventions

Handling of Character Encoding

To make processing of data in SMILA easier: If external data must be converted to a string (e.g. an attribute value), the crawler/fetcher or any other component accessing an external data source should try everything that is possible to ensure that the conversion is done using the correct encoding. For example, HTTP clients should use the encoding reported by the HTTP server. If the data source does not provide information about the character encoding, you can use the class org.eclipse.smila.utils.file.EncodingHelper that tries to convert a byte[] to a string by trying to detect the correct encoding from a byte[] by checking BOMs or checking XML and HTML content for instructions and finally by using UTF-8 or, if this fails, the default platform encoding. You may find this helpful.

On the other hand, if valid string data must be converted to a byte[] (e.g. if it is stored as a attachment after pipelet processing), the conversion must always use UTF-8 encoding.

Integrating a SMILA pipelet

As already shown in the overview above, SMILA offers the possibility to integrate your own service or piece of software into SMILA BPEL workflows.
In SMILA we simply call these workflows pipelines. A pipeline is the definition of a BPEL process (or workflow) that orchestrates pipelets and other BPEL services (e.g. web services).

The default and thus recommended technique to integrate simple and small functionality or software in SMILA is to provide a pipelet. Pipelets are easy to implement as they require only standard Java knowledge. They are not shared between multiple pipelines, even multiple invocations of a Pipelet in the same Pipeline do not share the same instance. The lifecycle and configuration of pipelets is managed by the workflow engine, not by OSGi runtime. Pipelets have full access to SMILA records by using the blackboard service, which makes it easy to read, modify, and store records. For further information on pipelets refer to the Pipelets documentation.

In general pipelets follow the same (sometimes optional) logical steps (of course this depends highly on the business logic to be executed). These steps are:

Read the configuration (optional)

Read input data from blackboard (optional)

Execute the business logic

Write result data to blackboard (optional)

In terms of the pipelet that implements the business logic you are totally free to use any desired technology. Some of the posibilities include:

Further reading

Integrating own workers

When the desired changes to the functionality are not simple and small or the desired functionality requires more than just accessing the records, it is recommended to integrate your functionality as new workers.
These workers have to be defined in the asynchronous job processing configuration and can then be integrated in workflows.

Description

A worker is an OSGi service, that implements the Worker interface, i.e. provides a name (to collect tasks and to be identified in workflows) and offers a threadsafe perform method, which takes a TaskContext object (generated by the WorkerManager) as an argument.

Normally the worker will handle a bulk of records in the perform method, manipulate the contained records, may access external services or stores and create new bulks of records.

The worker does not have to handle tasks or check if tasks are available. These menial tasks are done by the WorkerManager that cares for all registered workers, handles the invocations of their perform methods and copes with input and output bulks, up-scaling or exception handling. The worker just has to provide the perfom method to deal with the records.

If the worker requires direct access to the JobManager/TaskManager, e.g. because it is an initial worker and has to get initial tasks to start workflow runs without being triggered by previous workers, it must not register itself as a Worker service but has to tackle TaskManager and JobManager itself. Be careful, this is tedious work! So if possible stick to the Worker interface and let everything else be handled by the WorkerManager.

Further reading

Please consult at least the following pages about asynchronous job processing:

Further reading

Integrating alternative implementations of SMILA core components

The component-based architecture of SMILA even allows you to provide your own implementations of SMILA core components, since these are implemented as OSGi service components (see Declarativ Services) and can thus be exchanged in a standard way.

Include a new plug-in that exposes a service implementing the interface of the core component (e.g. ObjectStoreService)

modify the config.ini configuration file in SMILA.application to include and start the new plug-in instead of the plug-in provided by SMILA core.

build your application and run it.

Examples

A typical example could be an alternative implementation of the ObjectStoreService that does not store the objects in the file system but in memory or in a database.