AlfStream Module¶

This module provides an Apache Camel component and an Alfresco Repository component.

Changelog¶

The change log for Alfstream can be found here

Requirements:¶

Alfresco¶

Alfresco Dynamic Extensions
Java version 8
Version 5.0 and Above

Apache Karaf¶

Apache Karaf 4.0+
The Alfstream Camel Component

Compilation¶

We have created a plugin for gradle called the alfresco amp plugin which is a requirement for compiling all of our modules.

Installing the Alfresco Amp Plugin¶

Installing of the Alfresco amp plugin requires the following:

Java JDK 7 or above installed
Gradle installed

Cloning the repository¶

You can simply clone down our repository with your gitlab account:

git clone https://gitlab.parashift.com.au/open/alfresco-amp-plugin

Publishing to Local Maven¶

Once you have cloned the repository, it should be published into your gradle environment. This will by default publish to your local computer, but you can adjust build.gradle to publish to another Maven server if it's a requirement with:

gradle publish

Installation (Alfresco)¶

Parashift's AlfStream module is a Repo only amp, please follow our Installation guide on how to install this module.
Alfresco Dynamic Extensions is required to be installed, please follow Dynamic Extension Installation guide on how to install it.
For more information or a free trial, please click here

Installation (Karaf)¶

Installation of this module requires an instance of Apache Karaf to host Apache Camel.

Karaf is normally stored within the /opt/apache-karaf-*/ directory where * is the version number.

Windows Installation¶

To install prerequisite software you will need to do the following:

Download and install the latest version of Java JDK (version 8): http://www.oracle.com/technetwork/java/javase/downloads/index.html
Download and install Apache Karaf: http://karaf.apache.org/download.html
Extract this to a directory such as C:\apache-karaf-4.0.7
Run the application in a terminal with bin\karaf.bat

After this is done follow the Apache Karaf Manually instructions below.

Apache Karaf via Salt Stack¶

Rather than manually instantiating Karaf, utilising Salt Stack will allow the configuration of Karaf to take less time and ensure that things are deployed in the right order.

Create the following pillar configuration on the server:

  karaf:
    bundles:
     - mvn:org.apache.commons/commons-lang3/3.4
     - mvn:com.google.code.gson/gson/2.6.2
     - mvn:org.yaml/snakeyaml/1.17
    artifacts:
     - alfstream-1.*.*.jar

Run the following state command: salt-call state.sls karaf

Apache Karaf Manually¶

Install Apache Karaf as per the website instructions or windows install instructions above
Copy this file and put it in the karaf base directory, naming it bundles:

  feature:repo-add camel 2.17.0
  feature:repo-add hawtio 1.4.64

  feature:install camel
  feature:install camel-core
  feature:install camel-blueprint
  feature:install hawtio

  bundle:install mvn:org.apache.commons/commons-lang3/3.4
  bundle:install mvn:com.google.code.gson/gson/2.6.2
  bundle:install mvn:org.yaml/snakeyaml/1.17
  bundle:install mvn:org.apache.httpcomponents/httpclient-osgi/4.5.2
  bundle:install mvn:org.apache.httpcomponents/httpcore-osgi/4.4.4

Linux: Log in to the cli by running bin/client
Windows: Make sure you have an instance running by executing: bin\karaf.bat
Run the command source bundles in the client to install all the bundles
Copy and deploy the following files to the deploy/ directory:
alfstream-1.*.*.jar

Monitoring (Karaf)¶

Hawtio¶

To monitor that everything is going OK, you can utilise the web console hawtio via the following URL:

Location: http://<hostname>:8181/hawtio
Username: karaf
Password: karaf

Camel Routes¶

In the Camel tab of hawtio, you can see deployed routes that are in Apache Karaf.

Tracing¶

Warning: To trace an exchange, You must first disable Inclusion of Streams in the trace output. This is because viewing a file while tracing will consume the stream, not allowing it to be uploaded to Alfresco.

In the top right click on karaf then click Preferences.

Untick the Include Streams checkbox.

After Include Streams is unselected, click on one of the routes and select the Trace tab. Then select Start tracing. This will enable all exchanges passing through the route so that you can see the inputs/outputs.

Logs¶

The logs are accessible via the Logs tab. By default the Log Level of INFO is set, so you may need to adjust this to include DEBUG level routes using the CLI

CLI¶

run bin/client from the karaf directory (normally /opt/apache-karaf-*/)
(Optional) increase the log to include debug logging for parashift packages:

  log:set DEBUG com.parashift

Run log:tail to view the log

You will see debug logs from the com.parashift namespace, which will include the alfstream components.

Usage Examples¶

There are a few usage examples within the examples directory.

Setting up Configuration variables¶

All examples make use of configuration variables external to the blueprint file. To create these configurations:

Create a new file: etc/com.parashift.cfg
Add alfstream.uri, alfstream.username & alfstream.password, i.e:

  alfstream.url=http://localhost:8080/alfresco
  alfstream.username=admin
  alfstream.password=admin

Deploying examples¶

After you have set up the configuration variables, simply drop the blueprint xml file in the karaf deploy directory to start the route.

Debug Log Example¶

File: examples/alfstream-debug-log-blueprint.xml

The debug log example simply logs all exchanges to a debug log.

You will need a log level set to debug within karaf:

  log:set debug com.parashift

Two Way Blueprint¶

File: examples/alfstream-two-way-blueprint.xml

The two way blueprint will synchronise between two instances of Alfresco. This will synchronise all files and folders within a site called test.

You will need to set the following configuration properties:

alfstream.local.url: the Local alfresco instance (normally localhost, but could be a different server)
alfstream.local.username: the Local alfresco admin username
alfstream.local.password: the Local alfresco admin password
alfstream.remote.url: the Remote alfresco instance
alfstream.remote.username: the Remote alfresco admin username
alfstream.remote.password: the Remote alfresco admin password

Upsert Blueprint¶

File: examples/alfstream-upsert-blueprint.xml

Requires the upsert camel component. This will allow alfstream events to be synchronised to a seperate postgres database for reporting and analytics.