Alpaca Technical Stack

Alpaca contains several OSGI modules or bundles. They are grouped together as features and deployed to Karaf container.

OSGi

OSGi is a specification to develop and deploy modular Java applications. It allows for dynamic deployment (hot deployment) and dependency management.

The base unit of resources is called a bundle. Bundle is similar to a jar file, with additional information to be processed as an OSGi component. Several bundles can be grouped together into a Feature and installed together. OSGi bundles can be run on containers implementing the OSGi specification. Apache Karaf is one such container

Karaf

Apache Karaf is a container that can be used to deploy an array of applications such servlets, Apache Camel components, jars etc.

Karaf - Bundle - Hello World

Download a bundle to the islandora-playbook (ex to /home/ubuntu directory). An example hello world bundle is here.

In the Islandora 8 playbook, you can login to Karaf using ssh. The password is karaf. You can also use the client here: /opt/karaf/bin/client. Karaf client allows the use of Linux commands such as grep in addition to Karaf commands.

ssh -p 8101 karaf@localhost

Install the bundle:

karaf@root()> bundle
karaf@root(bundle)> install file:///home/ubuntu/helloworld-1.0.0.jar
Bundle ID: 242

The installation will return a bundle id. You can issue the list command to verify that bundle is on the list. Initially it will have Installed status.

As per OSGi specification, before a bundle can be started, it has to be Resolved. To resolve, issue the following command.

karaf@root(bundle)> resolve 242

You can start and stop the bundle as below.

karaf@root(bundle)> start 242
Hello World!
karaf@root(bundle)> stop 242
Goodbye World!
karaf@root(bundle)> 

Karaf - Features - Hello World

Karaf Features allows for bundles to be grouped, managed and deployed together. Features can be nested as well. Feature files of frameworks such as Apache Camel or Apache ActiveMQ can be used to deploy those services.

A simple Features file is as below.

<features>
  <feature name='greeter_server' version='1.0'>
    <bundle>file:///home/ubuntu/helloworld-1.0.0.jar</bundle>
    <bundle>file:///home/ubuntu/helloworld2-1.0.0.jar</bundle>
  </feature>
</features>

You can add the features to Karaf as below:

karaf@root()> feature:repo-add file:///home/ubuntu/features.xml

You can install the feature's bundles as below.

karaf@root(feature)> install greeter_server
Hello World 2 !
Hello World!

Uninstalling the feature.

karaf@root(feature)> uninstall greeter_server
Goodbye World 2 !
Goodbye World!

Gradle

Gradle is used by Alpaca as a build and package management tool. It is similar to Maven.

Apache Camel

Apache Camel is an integration framework that aids in implementing integration patterns.

Alpaca - Apache Camel HelloWorld

Maven has camel-archetype-blueprint which can be used to create apache-camel OSGi bundle project structure.

Creating a project/bundle under Alpaca

mvn archetype:generate -DarchetypeGroupId=org.apache.camel.archetypes -DarchetypeArtifactId=camel-archetype-blueprint -DarchetypeVersion=2.9.0 -DarchetypeRepository=https://repository.apache.org/content/groups/snapshots-g

However, it is easier to copy the structure of an existing project such as islandora-connector-broadcast.

cp -R islandora-connector-broadcast/ islandora-connector-helloworld

Open the project in your IDE. In Eclipse, you can go to File | Open Projects from File System and navigate the new folder.

We need to rename the configuration, java and build files to reflect the helloworld project.

• src/main/cfg/ca.islandora.alpaca.connector.helloworld.cfg
• src/main/java/ca/islandora/alpaca/connector/helloworld
• src/main/java/ca/islandora/alpaca/connector/helloworld/HelloworldRouter.java

Also change the content of the above file to log Hello World

package ca.islandora.alpaca.connector.helloworld;

import static org.apache.camel.LoggingLevel.INFO;

import org.apache.camel.builder.RouteBuilder;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class HelloworldRouter extends RouteBuilder {

    private static final Logger LOGGER = LoggerFactory.getLogger(HelloworldRouter.class);

    /**
     * Configure the message route workflow.
     */
    public void configure() throws Exception {

        // Hello World.
        from("timer:foo?period=5000").log(INFO, LOGGER, "Hello World");
    }
}

• src/main/resource/OSGI-INF/blueprint/blueprint.xml - Change the content of this file to reflect Helloworld package.
• src/build.gradle

apply plugin: 'osgi'

description = 'Islandora 8 HelloWorld'

dependencies {
    compile group: 'org.apache.camel', name: 'camel-core', version: camelVersion
    compile group: 'org.apache.camel', name: 'camel-blueprint', version: camelVersion
    compile group: 'org.apache.activemq', name: 'activemq-camel', version: activemqVersion
    compile group: 'org.slf4j', name: 'slf4j-api', version: slf4jVersion
    testCompile group: 'org.apache.camel', name: 'camel-test-blueprint', version: camelVersion
}

jar {
    manifest {
        description project.description
        docURL project.docURL
        vendor project.vendor
        license project.license

        instruction 'Import-Package', 'org.apache.activemq.camel.component,' +
                            "org.apache.camel;version=\"${camelVersionRange}\"," +
                            defaultOsgiImports
        instruction 'Export-Package', 'ca.islandora.alpaca.connector.helloworld'
    }
}

artifacts {
    archives (file('build/cfg/main/ca.islandora.alpaca.connector.helloworld.cfg')) {
        classifier 'configuration'
        type 'cfg'
    }
}

Building the bundle

To build this project, we have to update the Alpaca build settings. Include and add the project in Alpaca/settings.gradle.

include ':islandora-connector-helloworld'
project(':islandora-connector-helloworld').projectDir = "$rootDir/islandora-connector-helloworld" as File

Normally, we would also have to update the karaf/src/main/resources/features.xml file to include this bundle. However, we will be deploying the bundle directly into Karaf's Hot deployment directory. Thus, not needed at this time.

To build it from command line in Linux.

ubuntu:~/workspace/Alpaca$ sudo gradle w build

Deploying the bundle

• Upload the bundle to the Apache Karaf deploy directory: /opt/apache-karaf-4.0.5/deploy
• Login to Karaf. You can also use the Karaf client here: /opt/karaf/bin/client.

ssh -p 8101 karaf@localhost

• Verify that bundle is deployed

bundle:list

• See the log to confirm that the bundle is working.

log:tail

You should see a message like below:

2017-02-24 21:30:17,973 | INFO  | 12 - timer://foo | HelloworldRouter                 | 186 - ca.islandora.alpaca.islandora-connector-helloworld - 0.2.1.SNAPSHOT | Hello World

Apache ActiveMQ

Apache ActiveMQ is a JMS compliant Messaging Queue. Messaging client can make use of JMS to send messages.

Installing ActiveMQ

Installing ActiveMQ is relatively easy. Download the latest stable release here. Go to the activemq_install_dir/bin. Start the ActiveMQ by using the activemq script or batch file and start command.

$ cd activemq_install_dir/bin
$ ./activemq start

When ActiveMQ gets started, go to http://localhost:8161/admin/. You can login using admin:admin.

Note that ActiveMQ in Islandora 8 playbook does not have a UI.

References

• OSGI for Beginners
• Playing with Apache Karaf Console
• Karaf Quick Start
• ActiveMQ Introduction