Gyrex/Multi Tenancy Use Cases
Gyrex | |
Website | |
Download | |
Community | |
Mailing List • Forums • IRC • mattermost | |
Issues | |
Open • Help Wanted • Bug Day | |
Contribute | |
Browse Source • Project Set File |
Multi-tenancy in Gyrex is available using the context runtime, which provides a lot flexibility. This page lists a few multi-tenancy use cases and explains how they are supported in Gyrex.
Contents
Managing Tenants
Tenants can be managed programmatically using a Gyrex APIs, administered via the command line or using a web browser through the Gyrex Admin Console. Technically, they are called "a context" in Gyrex. Therefore, you will create contexts in a hierarchy which will represent your tenants.
Creating Tenants
Before you start creating tenants you need to think about the structure. Tenants can be organized hierarchically in Gyrex. The ROOT is represented using a simple slash (/). We recommend creating another hierarchy between the root and a tenant which identifies a common relationships of all the tenants.
Let's look at an example.
If you are building a multi tenant blogging system, the common relationship for all tenants is typically you: the vendor of the system. Now in order to create the first tenant (eg. a blog about nice kitchens), you would create a context for "Cool Blogs" (the vendor) first and then another context below the "Cool Blogs" context for the "Nice Kitchens" blog. This results in three contexts:
- Root (
/
) - Cool Blogs (
/coolblogs
) - Nice Kitchens (
/coolblogs/kitchens
)
Accessing a Tenant's Context
A context can be accessed programmatically in Gyrex as an IRuntimeContext
object. Typically, the IRuntimeContext
is provided to your code from Gyrex. Thus, you don't need to deal with the concern of detecting and establishing a IRuntimeContext
object.
In rare cases - for example, when you are building code that is managing/accessing multiple contexts - you can lookup a IRuntimeContext
from an IRuntimeContextRegistry
OSGi service.
Multi-Tenant Web Applications
Web applications in Gyrex come with multi-tenancy support out of the box. Any Gyrex web application is associated with a context and bound to a specific URL. Thus, for every incoming web request, Gyrex will detect the application and the tenant. Your code can access the IRuntimeContext
from the ServletContext
or the Application
instance. Additionally, if you register servlet classes instead of objects, you can use @Inject
annotations and let Gyrex inject IRuntimeContext
, context specific objects and/or context specific OSGi services (more below) into your servlets.
Multi-Tenant Web APIs
Multi-tenant web APIs using JAX-RS are implemented as Gyrex web applications. Your JAX-RS resources should use @Inject
/@Context
annotations for injecting IRuntimeContext
, context specific objects and/or context specific OSGi services (more below) into your servlets.
Tenant specific OSGi Services
When multiple OSGi service implementations are available, it's possible to delegate the concern of selecting a service implementation to the IRuntimeContext
. Your application code does not need to deal with selecting the proper OSGi service implementation for a particular tenant. By using LDAP style filters (as used bye the OSGi APIs), a IRuntimeContext
provides a way for transparently filtering up OSGi services. Currently, the filter configuration for each tenant can be modified from the shell using the context filter
command. Filters are inherited, i.e. a filter configured for a context will also be used by all its children without a custom filter configured.
Let's look at an example.
Our blog system offers integration with a user directory. For this purpose, an OSGi service is defined which specified a way to lookup users. You provide a default implementation for all blogs that looks up users from an in-house database. A special tenant does have it's own user directory which is accessible through a web api. An alternate implementation will be developed for this special tenant. However, it should not be used by default. Therefore, it will be registered with a much lower service ranking property. The context of the tenant can then be configured to use a special LDAP style filter to select that particular service (in favor for all other available implementations).
Tenant specific Objects
Up until OSGi R5, OSGi services are either global singletons or per bundle singletons. Sometimes, this might not be desirable especially when you want to have per-tenant specific object instances. In this case, a IRuntimeContext
can provide context specific objects which are created by a RuntimeContextObjectProvider
.
A RuntimeContextObjectProvider
is an OSGi service that you need to provide. It supports mapping of types to implementing classes and dependency injections for created objects. The same LDAP-style filter mechanism which applies to context specific OSGi service is used to lookup RuntimeContextObjectProvider
service instances of a specific tenant.