Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Gyrex/Developer Guide/Roles"
(New page: 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 <code>org.eclips...) |
|||
| (8 intermediate revisions by one other user not shown) | |||
| Line 1: | Line 1: | ||
| − | In Gyrex ''roles'' are used to control what bundles and what OSGi applications (OSGi application admin) will be started on a particular node. | + | In Gyrex '''''roles''''' are used to control what bundles and what OSGi applications (OSGi application admin) will be started on a particular node. |
== Dependencies == | == Dependencies == | ||
| Line 7: | Line 7: | ||
== Define Roles == | == Define Roles == | ||
| − | Roles are implemented using the Equinox Extension Registry. This decision was made in order to allow a declaritive approach for | + | 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 | + | In order to define a role you need to create an extension to the <code>org.eclipse.gyrex.server.roles</code> 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 <code>org.eclipse.core.runtime.applications</code> extension point. |
| + | === Example === | ||
| + | The following Example defines a role "My Server Role". | ||
| + | <source lang="xml"> | ||
| + | <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> | ||
| + | </source> | ||
| + | |||
| + | The role requires the bundle <code>com.abc.thridparty</code> to be started as well as the application <code>com.abc.my.application</code>. | ||
| + | |||
| + | |||
| + | == Activation Triggers == | ||
| + | Once roles are defined you also need to define an activation trigger. You can create different triggers depending on the [[Gyrex/Administrator_Guide#Operation_Mode|operation mode]] and the [[Gyrex/Development_Space/ZooKeeper_Interaction#ONLINE|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: | ||
| + | * <code>trigger="onBoot"</code> ... a node is started | ||
| + | * <code>trigger="onCloudConnect"</code> ... a node has successfully established its connection to the cluster | ||
| + | * <code>mode="development"</code> ... a node is operating in development mode | ||
| + | * <code>mode="production"</code> ... a node is operating is in production mode | ||
| + | * <code>nodeFilter="(...)"</code> ... a node matches a custom LDAP style filter (see <code> org.eclipse.gyrex.cloud.environment.INodeEnvironment.matches(String)</code>) | ||
| + | |||
| + | It's possible to combine different attributes together. | ||
| + | |||
| + | The <code>trigger="..."</code> 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. | ||
| + | <source lang="xml"> | ||
| + | <extension point="org.eclipse.gyrex.server.roles"> | ||
| + | <defaultStart | ||
| + | mode="development" | ||
| + | roleId="org.eclipse.gyrex.cloud.roles.leader" | ||
| + | startLevel="-10" | ||
| + | trigger="onBoot"> | ||
| + | </defaultStart> | ||
| + | </extension> | ||
| + | </source> | ||
| + | |||
| + | === 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. | ||
| + | <source lang="xml"> | ||
| + | <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> | ||
| + | </source> | ||
[[Category:Gyrex]] | [[Category:Gyrex]] | ||
Revision as of 03:46, 29 November 2012
In Gyrex roles are used to control what bundles and what OSGi applications (OSGi application admin) will be started on a particular node.
Contents
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 (seeorg.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>