Guide to using MultiTenantByUrl - tooltwist/documentation GitHub Wiki

This page explains how to use URLs to define multi-tenants on a website. To do multi-tenanting based on the website domain, or to get a background of the concepts used on this page, see Guide to using MultiTenantInterceptor.

Example URLS

https://english-courses.britishcouncil.org/kr/portal/
https://english-courses.britishcouncil.org/id/portal/
https://english-courses.britishcouncil.org/kw/portal/

Architectural Overview

This architecture depends upon two Servlet filters - one for the incoming request, and one for the outgoing response, and also a ToolTwist interceptor. If you wish to use URLs without /ttsvr/, then you will also need URLRewriteFilter.

Ryan, can you put the link here please?

From the user's browser the URL will be

http://mysite.com/china/portal/image.png

After the URLRewriteFilter the URL will be

http://mysite.com/ttsvr/china/portal/image.png

After the incoming filter (MultiTenantByUrlIncomingFilter) the URL will be

/image.png

At the same time, the filter will save "china" as the selector in a request attribute, for later use. (The URL above is passed to the forward method within the servlet engine, so it does not require the webapp prefix.

If the URL refers to a navpoint, the interceptor will be called. Based on the selector saved by the filter, it will redirect to the appropriate navpoint within the application. See the Guide to using MultiTenantInterceptor page for details on the configuration.

When a response is returned by the server, the outgoing filter (MultiTenantByUrlOutgoingFilter) will replace every instance of /ttsvr/ with the string in the original URL. For example, /ttsvr/china/portal/.

web.xml

The webapp configuration file web.xml will need a specification like this:

    <filter>
    	<!-- Filter outgoing reponses to modify URLs, replacing the
    	  -  webapp (/ttsvr/) with whatever the incoming filter replaced.
    	  -  This filter must be defined before the incoming filter.
    	 -->
        <filter-name>MultiTenantByUrlOutgoingFilter</filter-name>
        <filter-class>
            tooltwist.multitenant.MultiTenantByUrlOutgoingFilter
        </filter-class>
    </filter>
    <filter-mapping>
        <filter-name>MultiTenantByUrlOutgoingFilter</filter-name>
        <url-pattern>*</url-pattern>
    </filter-mapping>
    
    <filter>
    	<!-- Filter incoming requests and replace the part of the URL matching
    	  -  the pattern parameter. The {{SELECTOR}} is saved for use by the
    	  -  MultiTenantByUrlInterceptor, and the entire replaced part is saved
    	  -  so it can be used to replace /ttsvr/ in outgoing responses, by
    	  -  the MultiTenantByUrlOutgoingFilter filter. 
    	  -
    	  -  Note that the forwarding URL defined by the 'replaceWith' parameter
    	  -  does not require the webapp prefix (/ttsvr).
    	  -->
        <filter-name>MultiTenantByUrlIncomingFilter</filter-name>
        <filter-class>
            tooltwist.multitenant.MultiTenantByUrlIncomingFilter
        </filter-class>
        <init-param>
            <param-name>pattern</param-name>
            <param-value>/ttsvr/{{SELECTOR}}/portal/</param-value>        
        </init-param>
        <init-param>
            <param-name>replaceWith</param-name>
            <param-value>/</param-value>        
        </init-param>
    </filter>
    <filter-mapping>
        <filter-name>MultiTenantByUrlIncomingFilter</filter-name>
        <url-pattern>*</url-pattern>
    </filter-mapping>

Enabling the interceptor

The interceptor is enabled by config/interceptors/interceptor.multiTenantByUrl.xml.

    <interceptor>
    	<class>tooltwist.multitenant.MultiTenantByUrlInterceptor</class>
    	<enabled>false</enabled>
    </interceptor>

Site definitions

The sites are defined in site-conf/conf/multiTenantByUrl.xml. This file is identical to the standard multi-tenant interceptor except that the <domain> tag is called <selector>. Here is a simplistic example:

    <config>
            <site>
                    <selector>china</selector>
                    <project>ttdemo</project>
    
                    <navpoint>
                            <id>ttdemo</id>
                            <hierarchy>true</hierarchy>
                    </navpoint>
    
                    <!-- Replace the  home page -->
                    <navpoint>
                            <id>ttdemo-1</id>
                            <map>ttdemo-2</map>
                    </navpoint>
    
                    <properties>
                            <theme>blue chicken</theme>
                            <paymentGateway>paypal</paymentGateway>
                            <paypalClientId>171262535141</paypalClientId>
                    </properties>
            </site>
    
            <site>
                    <selector>korea</selector>
                    <project>ttdemo</project>
                    <navpoint>
                            <id>ttdemo-1</id>
                            <hierarchy>true</hierarchy>
                    </navpoint>
                    <properties>
                            <theme>cool sunset</theme>
                            <paymentGateway>paypal</paymentGateway>
                            <paypalClientId>9928877772</paypalClientId>
                            <freddo>frog</freddo>
                            <wallace>grommet</wallace>
                    </properties>
            </site>
    </config>

Availability

This functionality is available from ttWbd:8.3.3-SNAPSHOT onwards.