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.cfgsrc/main/java/ca/islandora/alpaca/connector/helloworldsrc/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.