Skip to main content
Jump to: navigation, search

Gyrex/Developer Guide

Gyrex
Website
Download
Community
Mailing List • Forums • IRC • mattermost
Issues
Open • Help Wanted • Bug Day
Contribute
Browse Source • Project Set File

Managing Bundle & OSGi Application Activation

In Gyrex roles are used to control what bundles and what OSGi applications (OSGi application admin) will be started on a particular node.

Dependencies

  • Bundle org.eclipse.gyrex.boot (Gyrex 1.0 or higher)
  • Equinox Extension Registry


Define Roles

Roles are implemented using the Equinox Extension Registry. This decision was made in order to allow a declaritive approach for defining roles without writing any line of Java as well as to support lazy activation. It may be possible to use DS in the future (bug 395332).

In order to define a role you need to create an extension to the org.eclipse.gyrex.server.roles extension point. Each role consists of an identifier, a name and references a set of bundles and/or applications to start. Applications must be defined using the Equinox org.eclipse.core.runtime.applications extension point.

Example

The following Example defines a role "My Server Role". 

<extension point="org.eclipse.gyrex.server.roles">
  <role id="com.abc.my.role" name="My Server Role">
    <requireBundle symbolicName="com.abc.thridparty" />
    <requireApplication applicationId="com.abc.my.application" />
  </role>
</extension>

The role requires the bundle com.abc.thridparty to be started as well as the application com.abc.my.application.


Activation Triggers

Once roles are defined you also need to define an activation trigger. You can create different triggers depending on the operation mode and the cloud online state. An addition start level can be set to apply some level of ordering to roles activation.

The following activation triggers are possible:

  • trigger="onBoot" ... a node is started
  • trigger="onCloudConnect" ... a node has successfully established its connection to the cluster
  • mode="development" ... a node is operating in development mode
  • mode="production" ... a node is operating is in production mode
  • nodeFilter="(...)" ... a node matches a custom LDAP style filter (see org.eclipse.gyrex.cloud.environment.INodeEnvironment.matches(String))

It's possible to combine different attributes together.

The trigger="..." defines when a role is processed.

onBoot means that roles will be started immediately when a node is started and a role becomes available. Thus, when a role is available at node start it will be started right away. When a role is installed (using p2) into a running node it will be started immediately after its successful installation. Any onBoot roles will be stopped when they are either uninstalled or the node is stopped.

onCloudConnect means that roles will be started when the node has successfully established a connection to the cluster. hen a role is installed (using p2) into a node that is already connected it will be started immediately after its successful installation. Any onCloudConnect roles will be stopped when they are either uninstalled or the node looses is connection to the cluster. They will be restarted automatically when the connection is established again.

Example Development Trigger

In development mode it's usually very comfortable to automatically start a role. For example, Gyrex itself uses the following trigger to automatically start an embedded ZooKeeper server in development mode. 

<extension point="org.eclipse.gyrex.server.roles">
  <defaultStart
      mode="development"
      roleId="org.eclipse.gyrex.cloud.roles.leader"
      startLevel="-10"
      trigger="onBoot">
  </defaultStart>
</extension>

Example Production Trigger

In production environment one usually does not want a particular role to start automatically but only when a specific configuration is done. For example, Gyrex itself uses the following trigger to start the Jetty server in production mode when a node is tagged with the tag webserver and successfully connected with the cloud. 

<extension point="org.eclipse.gyrex.server.roles">
  <defaultStart
      mode="production"
      nodeFilter="(tag=webserver)"
      roleId="org.eclipse.gyrex.http.jetty.roles.engine"
      startLevel="10"
      trigger="onCloudConnect">
  </defaultStart>
</extension>

Override at Startup

It is possible to override the roles that would be started by passing a command line argument when starting Gyrex. For convenience, the argument can also be added/set in the gyrex.ini configuration file. 

   -roles <roleId>[,<roleId>...]

Example for "Safe Mode" Startup

In case your server does not start normally, use the following roles to start Gyrex in a "safe mode" which will bring up the administration console.

Development Mode (with embedded ZooKeeper): 

   -roles org.eclipse.gyrex.admin.ui.role,org.eclipse.gyrex.cloud.roles.coordinator,org.eclipse.gyrex.cloud.roles.leader

Production Mode (without embedded ZooKeeper): 

   -roles org.eclipse.gyrex.admin.ui.role,org.eclipse.gyrex.cloud.roles.coordinator

Testing with JUnit

Gyrex supports and recommends writing tests with JUnit. Any JUnit tests must be run as JUnit OSGi plug-in tests in headless mode. Both, PDE Build and Tycho support such execution of tests. In order to assist developers with running and developing tests, Gyrex provides a few helpers for JUnit.

Dependencies

  • Bundle org.eclipse.gyrex.junit (Gyrex 1.2 or higher)
  • JUnit (4.10 or higher)

Integration Tests

Some tests may require a full Gyrex environment to be bootstrapped and running. We call those Integration Tests as they test a certain functionality in the system while operating/integrating with other essential services of the platform (for example, the cloud services backed by ZooKeeper).

Writing integration tests with Gyrex should be done by using the JUnit rules. JUnit rules allow defining dependencies/requirements for JUnit tests. Gyrex provides a rule which ensures that a Gyrex environment is bootstrapped and started before a test is run. Consequently, the server will be stopped after a test is finished. It’s recommended to implement dependencies as a @ClassRule inside a JUnit suite. This groups integration tests together and start the server only once and stop it after executing all tests.

Bundle Activation

Bundle activation is important when writing tests. Basically, you can not assume that a Gyrex server environment is fully bootstrapped and started in any bundle activator. This shouldn't be done anyway because OSGi is a dynamic environment and bundles can come and go at any time. Thus, make sure that you do not execute any logic during bundle activation which can fail if a Gyrex server environment is not available.

Instead, it's recommended to use Declarative Services or Gyrex Server Roles to trigger lazy activation once an environment is ready.

Example

The following example defines a JUnit suite for running integration test. 

import org.eclipse.gyrex.context.tests.internal.AllContextTests;
import org.eclipse.gyrex.junit.GyrexServerResource;
 
import org.junit.ClassRule;
import org.junit.runner.RunWith;
import org.junit.runners.Suite;
import org.junit.runners.Suite.SuiteClasses;
 
@RunWith(Suite.class)
@SuiteClasses({ /* list test classes here */ })
public class AllServerTests {
 
  @ClassRule
  public static final GyrexServerResource server = new GyrexServerResource();
 
}

TODO: Topics to cover

Note to self: Below is a random list of topics that we should cover. Any contribution is welcome! This is a wiki. Please feel free to edit and amend.

  • Servlets
  • Web Apps
  • HttpService
  • Contexts
  • Cloud Preferences
  • Repositories
  • Logging
Retrieved from "https://wiki.eclipse.org/index.php?title=Gyrex/Developer_Guide&oldid=323063"

This page was last modified 16:19, 28 November 2012 by Gunnar Wagenknecht.

Back to the top