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.