jesi tutorial

8/14/2019 jesi tutorial

1/37

JESI QuickStart

Page 1 of 37 Jahia Ltd, all rights reserved.

J ESI Caching Quic k St ar t

By MC

Draft Version: 1.4

Checkwww.jahia.org for regular updates
http://www.jahia.org/http://www.jahia.org/


2/37

JESI QuickStart


Changelog

29/11/2005: document created.

23/06/2006: added doc for absolute and alwaysInvalidate attributes.

12/07/2006: explained fragment number constraint.

20/10/2006: added custom class section, aclGroup templates, manualinvalidations, key generation overview, platform-specific AOP configuration

and other minor additions.

06/12/2006 : Portlet caching section added.


3/37

JESI QuickStart


1) Introduction

This guide will give the reader a quick overview of how to includeJava Edge-Side Includes (JESI)

caching tags in their templates. These tags are translated into ESI markup by the JSP compiler. JESItags also take care of setting the appropriate HTTP headers required by the ESI webcache server.

2) Recommended reading

http://www.oracle.com/webapps/online-help/jdeveloper/10.1.3/state/content/vtTopicFile.developing_with_ojsp%7Cojsp_rjesitaglib~html/nav

Id.4/navSetId._/

http://www.oracle.com/webapps/online-

help/jdeveloper/10.1.2/state/content/locale.en/vtTopicFile.developing_with_ojsp%7Cjesitags%7Ehtml/navId.4/navSetId._/

http://www.esi.org/jesit_tag_lib_1-0.html

3) Currently Supported JESI Tags

Jahia currently supports a JESI tags defined in \tomcat\webapps\jahia\WEB-INF\tld\jesi-tags.tld (a

modified subset of the Oracle JESI tags) which are:

jesi:templateo supported attributes:

control cache expiration maxRemovalDelay aclGroup

jesi:fragmento supported attributes:

control cache expiration maxRemovalDelay user group aclGroup absolute
http://www.oracle.com/webapps/online-help/jdeveloper/10.1.3/state/content/vtTopicFile.developing_with_ojsp%7Cojsp_rjesitaglib~html/navId.4/navSetId._/http://www.oracle.com/webapps/online-help/jdeveloper/10.1.3/state/content/vtTopicFile.developing_with_ojsp%7Cojsp_rjesitaglib~html/navId.4/navSetId._/http://www.oracle.com/webapps/online-help/jdeveloper/10.1.3/state/content/vtTopicFile.developing_with_ojsp%7Cojsp_rjesitaglib~html/navId.4/navSetId._/http://www.oracle.com/webapps/online-help/jdeveloper/10.1.2/state/content/locale.en/vtTopicFile.developing_with_ojsp%7Cjesitags~html/navId.4/navSetId._/http://www.oracle.com/webapps/online-help/jdeveloper/10.1.2/state/content/locale.en/vtTopicFile.developing_with_ojsp%7Cjesitags~html/navId.4/navSetId._/http://www.oracle.com/webapps/online-help/jdeveloper/10.1.2/state/content/locale.en/vtTopicFile.developing_with_ojsp%7Cjesitags~html/navId.4/navSetId._/http://www.esi.org/jesit_tag_lib_1-0.htmlhttp://www.esi.org/jesit_tag_lib_1-0.htmlhttp://www.oracle.com/webapps/online-help/jdeveloper/10.1.2/state/content/locale.en/vtTopicFile.developing_with_ojsp%7Cjesitags~html/navId.4/navSetId._/http://www.oracle.com/webapps/online-help/jdeveloper/10.1.2/state/content/locale.en/vtTopicFile.developing_with_ojsp%7Cjesitags~html/navId.4/navSetId._/http://www.oracle.com/webapps/online-help/jdeveloper/10.1.2/state/content/locale.en/vtTopicFile.developing_with_ojsp%7Cjesitags~html/navId.4/navSetId._/http://www.oracle.com/webapps/online-help/jdeveloper/10.1.3/state/content/vtTopicFile.developing_with_ojsp%7Cojsp_rjesitaglib~html/navId.4/navSetId._/http://www.oracle.com/webapps/online-help/jdeveloper/10.1.3/state/content/vtTopicFile.developing_with_ojsp%7Cojsp_rjesitaglib~html/navId.4/navSetId._/http://www.oracle.com/webapps/online-help/jdeveloper/10.1.3/state/content/vtTopicFile.developing_with_ojsp%7Cojsp_rjesitaglib~html/navId.4/navSetId._/


4/37

JESI QuickStart


alwaysInvalidate

jesi:codeblocko supported attributes:

execute

jesi:control

o supported attributes: control cache expiration maxRemovalDelay

4) Example 1

The current version of the corporate_templates contains

\tomcat\webapps\jahia\jsp\jahia\templates\mySite\corporate_portal_templates\simple.jsp which wewill take as the basis for our first example:

jsp:paramname="displayDetails"value="true"/>

where getUserBackgroundColourPreference() returns a unique string for the colour selected by thecurrent user.

The functionality of the 'group' and 'user' attributes are roughly identical

since the 'user' attribute could be used to achieve the same effect bysetting

However, this is not recommended. The 'user' attribute should only be

used for specifying usernames and 'group' for anything else. If we only

used the 'user' attribute then we'd introduce the possibility of naming

collisions between identical usernames and a group names.

Note that if the 'user' attribute is also set, it will take precedence and the 'group' attribute which willbe ignored.

aclGroup sharing

The jesi:fragment tag also supports an additional attribute called aclGroup. Instead of using theusername as in the 'user' attribute as defined in the default behaviour, or generating an arbitrary string

for the 'group' attribute, you can use the aclGroup attribute to share fragments between those who

belong to the same ACL groups.

This is done by basically automatically generating a unique key based on the current user's ACL

group membership. This key is later appended to the fragment URL so that all users with the same

ACL group memberships will point to the same fragment.

The aclGroup attribute supports the following values:

'true' (reserved) : activate the aclGroup fragment caching.

['false'] (reserved) : deactivate the aclGroup fragment caching and revert to user/groupcaching instead. This is the default behaviour.

any other value : activate the aclGroup fragment caching and append this string value to

the unique key based on the user's ACL group membership. This basically compounds the

functionality of the 'group' and 'aclGroup' attributes. So for example, if we want to rendera footer which displays a containerList in a user specified background colour, all users


10/37

JESI QuickStart


with the same background colour settings in their profiles and with the same groupmemberships will see the same list of containers with the same background colour by

setting the tag to:

Note that if the 'user' or 'group' attribute is also set, it will take precedence and the 'aclGroup'attribute will be ignored.

If neither 'user', 'group' nor 'aclGroup' attributes are defined, the default behaviour of thejesi:fragment tag is to cache each fragment by user.

If any content enclosed in this fragment exhibits a special ACL entry forthe current user's name, then a specific group for that single user iscreated. This is because this user might have specific rights added or

removed on the content referenced in this fragment.

Absolute fragments

The group/user/aclGroup attributes alone make it possible to share fragments between users of the

same page, but not between users on different pages. The absolute attribute addresses this issue.

In Jahia, a page is defined by its unique /pid/xxx value. So all users accessing a page with say /pid/1can share fragments. However, fragments cannot be shared between pages /pid/1 and /pid/2.

Using the 'absolute' attribute, fragments can be made available to all pages independent of their pid or

JSP template. The 'absolute' attribute must be used in conjunction with a group/user/aclGroup

attribute to allow cross-page user or group sharing of fragments.

The absolute attribute supports the following values:

'true' or 'yes': activate absolute fragment sharing.

['false'] or 'no': (default) deactivate absolute fragment sharing.

This is a powerful way of sharing content and maximizing cache usage. However it must be usedwith caution because the content generated in an absolute fragment must be identical on all pages

sharing this content, otherwise we have no idea what will be displayed. In order to do this, every JSP

template must have the exact same code between absolute fragment tags for each absolute fragment.


11/37

JESI QuickStart


This is due to the fact that the ESI server can query any page for an absolute fragment and it willshare it with any other page that displays this absolute fragment.

For example, if an absolute fragment JSP code looked like this:

My footer html here.

then we could safely paste it in all JSP template and share it between all users and instantiated Jahiapages (i.e. pid pages).

However if an absolute fragment JSP code looked like this:

int fontsize = (int) ( 8 + processingContext.getPid() );

My footer html here.

In this example, the fontsize variable varies with the current page's pid number and therefore is

specific to each page. Thus, the first page to generate this absolute fragment and store it in the ESI

cache, will be the exactly the same one displayed by every other page displaying this absolutefragment, independent of their current pid. This of course isnt workable. One couldnt use absolute

fragments for this example.

It is therefore important that the content of an absolute fragment generated by any page

be identical, no matter what page is queried for that fragment.

Usage Example 1:

This footer fragment will be shared by all pages, regardless of the original JSP template used.

Usage Example 2:

This fragment will be shared users with the same footer background colour preference, regardless ofthe page or the original JSP template used.

Usage Example 3:


12/37

JESI QuickStart


This fragment will be shared by all users belonging to the same user groups, regardless of the page or

the original JSP template used.

Usage Example 4:

This fragment will be shared by a same user across all pages and regardless of the original JSP

template used.

The following diagram summaries the possible types of fragment sharing:

jesi:fragment Attributes Sharing between users Sharing between pids

aclGroup YES (between users belonging to the

same ACL groups)

NO

aclGroup + absolute=true YES (between users belonging to thesame ACL groups)

YES

group YES NO

group + absolute=true YES YESuser NO NO

user + absolute=true NO YES

(no sharing attribute) NO NO

(no sharing attribute) +absolute=true

NO YES

alwaysInvalidate fragments

The alwaysInvalidate attribute was introduced to force invalidations of fragments before its

expiration time or even when no content inside it was changed. It is currently used exclusivelyaround the page Mode tabs (i.e. Live/Preview/Compare/Edit) in the admin_menu.inc JSP file. We do

this to ensure that it will be invalidated from the ESI cache in all modes if anything is changed on the

page. This is to guarantee that the tabs are updated to reflect the current status of the page.

The alwaysInvalidate attribute supports the following values:

'true' or 'yes': this fragment will be invalided if any other fragment (or template) isinvalidated on the same page.

['false'] or 'no': (default) will only be invalidated when explicitly necessary.

If true, then a fragment is always invalidated if something is changed anywhere else on the page, inevery mode (e.g. live/preview/compare/edit modes). This is used for example on the edit tabs so that


13/37

JESI QuickStart


the fragment containing the tabs is invalidated in every mode if any other fragments is invalidated.This is due to the fact that the Live mode is only invalidated when content is validated through the

workflow; if this was the case then the tabs in Live mode would not always be coherent.

This attribute is useful to use on fragments that need to be invalidated if anything is changed on thepage. You can use it in conjunction with aclGroup/group/user attributes. It also works with 'absolute'attribute but review carefully if that is the behaviour you want.

Make sure that the total number of declared fragments on a page isconstant, no matter what logic is executed. It is also recommended that

for a given fragment number, no matter what logic is executed in the JSP,

it should always remain functionally similar. This is because Jahia keeps

track of fragments by their order of appearance in the JSP template. Ifthese guidelines are not followed some invalidations incoherencies might

occur.

So, for example, given the following template:

Display page title

Display user info

Display page header menu


Display main content

There are two problems here: the non-constant number of total fragments

(depending on if user if logged or not) and the varying order in which

they appear. So the user info fragment #2 for logged users will also bethe pageHeader fragment #2 for guests. A better way to write this would

be:


14/37

JESI QuickStart


Display page title

Display user info


Display main content

7) Codeblock Tag

You can optionally use codeblock tags within the template tag, outside of any fragments, to mark

conditional execution of blocks of code.

To avoid needlessly repeating the execution of expensive template code, strategically place the code

within JESI codeblock tags. Configure each codeblock tag according to when you want the code

within it to be executed (whenever the template is requested, whenever a fragment is requested, or

always).

...

...request-dependent JSP content...

...

template: The enclosed code will only be executed when the current request is requesting thetemplate. This is equivalent to not putting a codeblock tag around the code.

fragment: The enclosed code will only be executed when a fragment is being fetched, but

wont be executed when the template is requested. always: The enclosed code is always executed (for both fragment and template requests).

Its behaviour is identical to that described in http://www.oracle.com/webapps/online-help/jdeveloper/10.1.2/state/content/locale.en/vtTopicFile.developing_with_ojsp%7Cjesitags%7Eht

ml/navId.4/navSetId._/
http://www.oracle.com/webapps/online-help/jdeveloper/10.1.2/state/content/locale.en/vtTopicFile.developing_with_ojsp%7Cjesitags~html/navId.4/navSetId._/http://www.oracle.com/webapps/online-help/jdeveloper/10.1.2/state/content/locale.en/vtTopicFile.developing_with_ojsp%7Cjesitags~html/navId.4/navSetId._/http://www.oracle.com/webapps/online-help/jdeveloper/10.1.2/state/content/locale.en/vtTopicFile.developing_with_ojsp%7Cjesitags~html/navId.4/navSetId._/http://www.oracle.com/webapps/online-help/jdeveloper/10.1.2/state/content/locale.en/vtTopicFile.developing_with_ojsp%7Cjesitags~html/navId.4/navSetId._/http://www.oracle.com/webapps/online-help/jdeveloper/10.1.2/state/content/locale.en/vtTopicFile.developing_with_ojsp%7Cjesitags~html/navId.4/navSetId._/http://www.oracle.com/webapps/online-help/jdeveloper/10.1.2/state/content/locale.en/vtTopicFile.developing_with_ojsp%7Cjesitags~html/navId.4/navSetId._/


15/37

JESI QuickStart


To maximally boost performance, we highly recommend using this tag profusely (yet thoughtfully).

8) Control Tag

The JESI control tag controls caching characteristics for JSP pages. You can use a JESI control tagin the top-level page or any included page, but it is not mandatory.

For example, we use the control tag in the sitemap.jsp in the corporate_templates to prevent the entirepage from being cached:


16/37

JESI QuickStart


jsp:include>

jsp:include>

Yourhasthefollowingnews:


17/37

JESI QuickStart


%>

Example2.jsp

The JSP first declares a skeleton cached on a per-user basis which automatically self-expires every

100 minutes:

The codeblock tag is then used to make sure that common variable declarations, javascript includes

and necessary JSP includes are executed every time both a fragment or the skeleton is requested:

Next we want to render the top menu bar. For better performance, it is preferable to include this code

inside another codeblock tag; this time with the execute="template" attribute. This ensures that we

only execute this code when re-generating the skeleton and not whilst fetching each fragment. This isbecause when we fetch a fragment, the generated topMenu bar (along with all the other skeleton

content) is simply ignored. So its an unnecessary burden to generate it to fetch a single targeted

fragments output.

Next we declare a standard per-user cached fragment:

We then make use of the aclGroup caching mechanism in the following snippet:


18/37

JESI QuickStart


We didnt use a per-group based caching since, although the page title is identical for everyone, not

everyone has the same editing rights on it.

The next snippet of interest is the one displaying the current time:

Thecurrenttimeis

We want to make sure this is never cached so each page refresh will cause the display of the correcttime.

The more interesting fragment declaration is the one displaying the news entries:

s News :

We couldve used a aclGroup="yes" in the fragment declaration to share this fragment across allusers with the same ACL group permissions. However, notice that each displayed news entry is

preceded with the users current organization name. The name of the organization is retrieved from

the current users properties. So we use instead aclGroup="" to share this


19/37

JESI QuickStart


fragment across all users with the same ACL group permissions and with the same organizationname in their profile.

Note that the organization String declaration is always executed using a codeblock tag because it isboth used by the skeleton to generate the caching attributes and by the fragment itself.

Finally, the footer is shared between all users using a static group:

10) Declaring Custom Class Usage

In order to make the invalidation of fragments and templates on the remote ESI cache server, Jahia

needs to know what content is displayed where and if it has been updated. Once Jahia knows, say, aContainer A has been added to a ContainerList B, it will look for all pages displaying ContainerList

B and invalidate those on the ESI server. Otherwise these pages will display the outdated version of

ContainerList B. The fragments (or templates) referencing, calling or displaying ContainerList B willbe invalidated via a SOAP xml invalidation message from Jahia to the remote ESI server.

To detect which content objects (e.g. Pages, Fields, Containers or ContainerLists) your JSPs

references, calls or displays, Jahia uses Aspect-oriented programming (AOP) to detect at execution-time the method calls to content objects made from within the JSPs. Jahia is then able to infer and

store which content objects were called from and to which fragment or template they belong.

When an content object is updated/modified/deleted, an eventlistener catches these events and

invalidated any pages that reference that updated content object.

This is normally transparent to the template developer, except in the case when custom classes are

called from within your JSPs. If the code executed in these classes does not reference any Jahia API

calls, then this section does not apply. However, if your classes make use of Jahia content objects,

then they need to be declared to the AspectWerkz AOP mechanism. This will allow Jahia to trackwhich content objects your code made use of and to locate in which template or fragment it did so.

For example, say we have developed a Java class to retrieve the size of a ContainerList:

package org.reader.mycode;

import org.jahia.data.JahiaData;import org.jahia.data.containers.JahiaContainerList;

import org.jahia.exceptions.JahiaException;
http://aspectwerkz.codehaus.org/http://aspectwerkz.codehaus.org/


20/37

JESI QuickStart


/**

* User: Reader

* Date: Jul 31, 2006

* Time: 11:09:39 AM

* Copyright (C) Jahia Inc.

*/publicclass MyClass {public MyClass () {

}

publicstaticint getContainerListSize (

JahiaData jData,

String listName,

int pageId) throws JahiaException {

JahiaContainerList absoluteContainerList =

jData.containers().getAbsoluteContainerList(listName, pageId);

if (absoluteContainerList!=null)

return absoluteContainerList.getFullSize();else

return0;

}

}

This class is called from your custom JSP, such as:


21/37

JESI QuickStart


My list size is : listSize

If AOP doesnt know about MyClass, then if ContainerList id=10 is modified, the corresponding

o do this, simply open the \YOUR_TOMCAT\webapps\jahia\WEB-INF\aol.xml and add the path to

page will not be invalidated.

T

your MyClass class there. An already completed sample file is available at

\YOUR_TOMCAT\webapps\jahia\WEB-INF\aol.xml.custom.example for the MyClass example. In

short, the package to your classes needs to be included :

as well as the scope to your classes in each pointcut declaration :

ORwithin(org.reader.mycode.MyClass+.*(..))

This means that AOP capturing of content object Jahia API calls will occur whilst executing the any

MyClass methods, including MyClass subclasses. TheMyClass+means all subclasses of MyClass

and *(..) means any method with any number of parameters. You can narrow the scope of course

For more details on the syntax ofaop.xml, please refer to:

.

ttp://aspectwerkz.codehaus.org/x lh ml_definition.htm .

11) Configuring AOP for your Platform

y default, AOP is configured by default to run on the Apache Tomcat platform. If you intend to useB

Jahia on another platform such as WebSphere or WebLogic, you need to make a few minor changes

to the \YOUR_SERVER\webapps\jahia\WEB-INF\aol.xml file.
http://aspectwerkz.codehaus.org/xml_definition.htmlhttp://aspectwerkz.codehaus.org/xml_definition.htmlhttp://aspectwerkz.codehaus.org/xml_definition.htmlhttp://aspectwerkz.codehaus.org/xml_definition.htmlhttp://aspectwerkz.codehaus.org/xml_definition.html


22/37

JESI QuickStart


he following lineT

as well as any occurrence of :

within(org.apache.jsp.jsp.jahia.templates..*)

need to be changed. The package org.apache.jsp.jsp.jahia.templates is the package Tomcat compiles

e could also have used the following declaration :

and packages the default Jahia templates to. It tells AOP to capture Jahia content update method-calls

made from within JSP templates only, and not anywhere else in the Jahia code.

W

with :

within(org.apache.jasper.runtime.HttpJspBase+)

which has the same effect since all compiled JSP classes are derived from the same HttpJspBase.Again, refer to http://aspectwerkz.codehaus.org/xml_definition.html for more syntax details.

A different servlet container, such as WebSphere, will probably have a different template package

name or JSP base class. This can be done by inspecting the servlet code generated from the

compilation of JSP files (to be found in the temporary directory where your servlet container

compiles JSP files). Youll want to pay special attention to either the package statement or theextends/implements statements.

When you successfully configure your platform to work with AOP, feelfree to contribute your updated AOP file to Jahia so that we can pre-

package pre-configured aop.xml files for various platforms.

12) Manual Invalidations

parallel to automatic invalidations carried out by Jahia when content is modified, templateIndevelopers can initiate invalidations manually to force the remote ESI server(s) to clear specific
http://aspectwerkz.codehaus.org/xml_definition.htmlhttp://aspectwerkz.codehaus.org/xml_definition.html


23/37

JESI QuickStart


cache entries for skeletons (i.e. templates) and/or fragments. This is useful if the changes aregenerated by your JSP code logic, and not by Jahia content changes such as in forms.

The invalidations methods discussed here are located in the

org.jahia.services.esi.EsiSOAPInvalidatorService class. Javadoc details are

http://www.jahia.org/javadoc-dev_5/org/jahia/services/esi/EsiSOAPInvalidatorService.html

Invalidating a whole page

The following code will invalidate the current page and all its fragments in all modes (e.g. Live,

Preview and Edit modes), in all languages and over all users:

All fragments of any type (e.g group, aclGroup or user) are invalidated, including any absolute

fragments referenced by this page.

A more selective method allows one to include or exclude non-absolute and absolute fragments:

SOAPInvalidatePageAndAllFrags(ProcessingContext pc, int pid,

boolean includeAbsoluteFrags,

boolean includeNonAbsoluteFrags)

Note that if absolute fragments are included then other pages will have to be re-aggregated on the ESI

server if they also reference these absolute fragments.

Invalidating non-absolute fragments

Sometimes, youll want to invalidate only a specific fragment on a page. This is done using the

following method:

SOAPInvalidateFrags(ProcessingContext pc, int pid, Set fragIDs)

Youll need to retrieve the fragment id, which is the position number it appears on the page, from the

current PageContext. The PageContext object is updated at the very end of the fragment execution,

so it must be executed just after the final closing tag. If this is not the case in your

code, you might be retrieving the fragment id of the previous fragment.
http://www.jahia.org/javadoc-dev_5/org/jahia/services/esi/EsiSOAPInvalidatorService.htmlhttp://www.jahia.org/javadoc-dev_5/org/jahia/services/esi/EsiSOAPInvalidatorService.html


24/37

JESI QuickStart


The fragment will then be synchronously removed from the ESI cache, which means that once the

SOAPInvalidateFrags method is called, the fragment is not in the ESI cache anymore. Note thatyour invalidation will only take effect for the next request to the page. So you cannot invalidate a

fragment and regenerate it, all in the same request. Only on the next request will the regenerated

fragment be displayed.

There is little point in executing this method inside the actual fragment which you want to invalidate,

since if the fragment is being executed then its updated version is being sent to the ESI server.

Usually, youll want to call the SOAPInvalidateFrags method from within the enclosing template or

from within another fragment. So if a template or a fragment is being regenerated, you can force the

invalidation of another fragment within the page or the template itself on the current or other pages. It

is used for example in the corporate_templates_v2 in \common\top.inc for the ESI flush button.

The following code will invalidate the above fragment:

Lots of fragment content goes here...

fragmentID=

The invalidation method will only be called when the template is being regenerated. To limit or

expand the times when your invalidation code is executed, use the jesi:codeblock tag. For example,

the following code snippet will be executed only when a fragment is being generated:


25/37

JESI QuickStart


%>

Invalidating absolute fragments

To invalidate a specific absolute fragment, you need to retrieve its unique identifying key first, assuch:

Absolute ESI fragment content here

absoluteFragmentKey=

Again, make sure the getAttribute method is called just after the closing tag to be

sure to get the key for the targeted fragment.

Invalidating for a user

To a certain extend, you can invalidate all the templates/fragments generated by a given user. Bygenerated, it is meant fragments that were generated in response to a request from a given user. So a

shared fragment X (e.g. group, aclGroup or absolute) might be displayed on user As page, but it

mightve been generated by user B. So if we invalidate all entries for user A, fragment X will not beinvalidated even if it is displayed by user A.

Therefore this method is effective for invalidations of user-specific fragments and for non-

aclGrouped templates. If the template are non-aclGrouped (meaning that they are generated for eachuser) then all these templates will be invalidated with this command. All aclGroup=true templates

used by a user will not necessarily be invalidated, except if the current user has generated them.

SOAPInvalidateAllUserEntries(ProcessingContext pc, JahiaUser jahiaUser)

SOAPInvalidateAllUserEntries(ProcessingContext pc, Set users)

Invalidating the whole cache


26/37

JESI QuickStart


It is also possible to empty the entire ESI cache with a single command:

emptyEsiServerCache(SettingsBean settings,boolean emptyOnlyHtml)

The emptyOnlyHtml parameter controls the invalidation of only Jahia pages and fragments, or ofeverything including cached Javascript, image, css and other non-Jahia-page objects.

Combo method

The following method allows the invalidation of multiple pages (and all their fragments) as well as

all the entries generated by a set of users, all in one go.

SOAPInvalidatePagesAndAllFragsAndAllUserEntries(ProcessingContext pc,

Set pids,

Set users,

boolean includeAbsoluteFrags,boolean includeNonAbsoluteFrags)

Content-based invalidation mechanism

Once a content object is changed, Jahia will automatically invalidate all the templates/fragmentswhich display it. If however, you want to force this process from your JSP templates, you need to fire

an event that contains a reference to this content object and Jahia will do the rest.

Jah ctUpiaEvent obje datedEvent =

new JahiaEvent(this, Jahia.getThreadParamBean(), myContentObject);

ServicesRegistry.getInstance ().getJahiaEventService ()

.fireContentObjectUpdated(objectUpdatedEvent);

where myContentObject can be either ContentContainerList, a ContentContainer,ContentPage, a ContentField etc.

The invalidation will be executed on the next request made to the Jahia server.

It will also invalidate content in the Preview, Compare and Edit mode.

To invalidate in the Live mode also, the following command is used instead:

(new EsiInvalidationEventListener()).invalidateContentObjectInAllModes(Jahia.getThreadParamBean() , myContentObject);

GUI invalidation mechanisms


27/37

JESI QuickStart


Another way to manually clear the ESI cache and without any coding required, is to use JahiasAdministration Center or the ESI servers Administration Center. Note that if you modify one or

more files in your template directory, you do not need to initiate a manual ESI cache flush. This is

done automatically by Jahia when it detects any file changes in the template directory.

13) Portlet Caching

If you are using Portlets in your JSPs, here is what you need to know about using them with ESI

caching.

Usage:

One portlet per page

Portlets need to be enclosed within a jesi:fragment tag. The main difference is that youll want to set

your expiration delay to 0. Normal rules apply to the remaining the fragments on the page, as well

as the enclosing jesi:template. This means that the fragment containing the portlet will always beregenerated, but the rest of the page can be cached.

Taking the simple.jsp as an example and assuming that the available boxes are all portlets, then

simply inserting a 0 expiration will do the trick:

Multiple portlets per page

If you have more than one portlet per page, then you can put them all in the same 0 expiration

fragment or in separate 0 expiration fragments. Since each portlet fragment is generated during the

same request as the other portlet fragments, information sharing between portlets is thereforesupported.

ESI Caching one portlet per page

Portlet fragments can still be cached by ESI, using a non-zero expiration value, but with certain

limitations.
http://en.wikipedia.org/wiki/Portletshttp://en.wikipedia.org/wiki/Portlets


28/37

JESI QuickStart


The cache key on the ESI server for fragments is based on the request URL for the page (please read

Key Generation Overview section first). In the case of a page containing a portlet, URLs can be of the

form :

http://localhost:8081/jahia/Jahia/site/mySite/pid/3/jesi_appid/227_2/_ns/YWphaGlhX3BvcnRsZXRf

dGVzdDo6dGVzdHBvcnRsZXQ6Oi01OGFhOTdkZDoxMGY0ZGRjYjM1NjotN2ZmZnxm

where the part after /jesi_appid/ can be different for each request. So we abstract away this variableportlet part in our cache key to

http://localhost:8081/jahia/Jahia/site/mySite/pid/3/jesi_appid/

This entails that there will only be one cache entry no matter what the variable portlet URL part is.The consequence is that means that the latest version of the portlet will be served, no matter what the

current variable portlet URL part is. For some portlets, this is not a problem. For others, it might

mean that if a user clicks inside the portlet but still gets the cached version (at least until it expired or

is manually invalidated by yourself).

ESI Caching multiple portlets per page

If there are multiple portlet fragments on a page and some of them are cached, be sure that there is no

information sharing between them. This is because portlets will be generated on an individual basisper request, and not all in the same request. If your portlets are independent, then this isnt an issue. If

they are, this might lead to

unexpected behaviours.

ESI Sharing portlet

User, group and aclGroup based fragment sharing also applies to portlet fragments. So each user canhave his own version of the portlet, or each user in the same group, or with the same rights. This does

not absolve you from following the restrictions due to the truncated portlet URL in the cache key.

14) Final Remarks

Template Group Sharing

In practice, template sharing is limited since a group shared skeleton cannot contain fragments

individual to each user. All fragments in a shared skeleton are the same. Let us look at an example:

.
http://localhost:8081/jahia/Jahia/site/mySite/pid/3/jesi_appid/227_2/_ns/YWphaGlhX3BvcnRsZXRfdGVzdDo6dGVzdHBvcnRsZXQ6Oi01OGFhOTdkZDoxMGY0ZGRjYjM1NjotN2ZmZnxmhttp://localhost:8081/jahia/Jahia/site/mySite/pid/3/jesi_appid/227_2/_ns/YWphaGlhX3BvcnRsZXRfdGVzdDo6dGVzdHBvcnRsZXQ6Oi01OGFhOTdkZDoxMGY0ZGRjYjM1NjotN2ZmZnxmhttp://localhost:8081/jahia/Jahia/site/mySite/pid/3/jesi_appid/227_2/_ns/YWphaGlhX3BvcnRsZXRfdGVzdDo6dGVzdHBvcnRsZXQ6Oi01OGFhOTdkZDoxMGY0ZGRjYjM1NjotN2ZmZnxmhttp://localhost:8081/jahia/Jahia/site/mySite/pid/3/jesi_appid/227_2/_ns/YWphaGlhX3BvcnRsZXRfdGVzdDo6dGVzdHBvcnRsZXQ6Oi01OGFhOTdkZDoxMGY0ZGRjYjM1NjotN2ZmZnxmhttp://localhost:8081/jahia/Jahia/site/mySite/pid/3/jesi_appid/227_2/_ns/YWphaGlhX3BvcnRsZXRfdGVzdDo6dGVzdHBvcnRsZXQ6Oi01OGFhOTdkZDoxMGY0ZGRjYjM1NjotN2ZmZnxmhttp://localhost:8081/jahia/Jahia/site/mySite/pid/3/jesi_appid/227_2/_ns/YWphaGlhX3BvcnRsZXRfdGVzdDo6dGVzdHBvcnRsZXQ6Oi01OGFhOTdkZDoxMGY0ZGRjYjM1NjotN2ZmZnxm


29/37

JESI QuickStart


. Fragment 1 .

. Fragment 2 .

.

. Fragment 3 .

.

. Fragment 4 .

.

The template is shared between all users using the static group identifier salesperson. However,

Fragment 1 uses a user property to define sharing. The first time this template is executed the resultwill be correct for the requesting user, in that Fragment 1 will use his/her preferred background

colour defined in his/her profile. The skeleton is then stored in the ESI webcache.

However, all subsequent users requesting this page will also get this cached skeleton. The problem is

that the include link for Fragment 1 is hardcoded. It points to the fragment group defined by the first

users background colour preference. As a result all users, no matter what preferred background

colour is declared in their profile, will get the same instance of Fragment 1.

The same goes for Fragment 2. Here the default jesi:fragment behaviour per user caching is

invoked since no attribute is define. All users will see the Fragment 2 initiated by the first user

requesting this fragment.

Only Fragment 3 is correctly defined here. It is shared on a static basis via the salesProjections

group. There is no danger of its content being shared incorrectly.

Fragment 4 is incorrect since the rights of the first user to generate this group template will be used to

generate the include link to Fragment 4. Another user, with different rights, should point to another

aclGroup fragment. However this will not be the case here. Therefore aclGroup fragments should notbe used with group sharing.

For these reasons, it is preferable to minimize group template (i.e. skeleton) sharing whilst

maximizing fragment sharing. By minimizing the content stored in each template and usingjesi:codeblock tags, the workload necessary to generate skeletons on a per-user basis (instead of on a

per-group basis) can be kept to a minimum.

Template aclGroup Sharing


30/37


31/37

JESI QuickStart


Nested fragment tags are currently not supported.

Jahias /cache/off, /cache/offonce and /cache/bypass URL parameters are supported bythe ESI server. This feature can be disabled in the tomcat\webapps\ROOT\WEB-

INF\config\data.xml file.

The maxRemovalDelay attribute is currently ignored.

We intend to add fine grained control of the behaviours to adopt for any errors that

may occur during fragment generation. For example, choose between displaying adefault error message in place of an inaccessible fragment, using the stale yet already

cached version of a fragment or displaying custom fallback content.

We intend to add the jesi:include tag to be used in replacement of the jsp:include tag.This will allow absolute fragments to be shared between pages and not just users of

the same page.

15) Key Generation Overview

In order to get a better grasp of template and fragment sharing, a schematic overview of the key

generation process is given here. These keys are used as entry points into hashmaps on the ESI server

to store fragments and templates.

The following simplified example is for illustrative purposes, the exact inner workings of Jahias ESI

might be slightly different (see source code for details).

Template/Skeleton

So given the following JSP:

Header

Frag1 content


32/37

JESI QuickStart


Footer

For a request to http://myEsiServer:8081/jahia/Jahia/pid/1 by user John and if the page isnt yetcached, the ESI server must first fetch the skeleton (i.e. esi template) for the page to determine which

fragments are required. Jahia will roughly generate the following html for this skeleton request from

the ESI server:

Header

Footer

The skeleton is stored in the ESI servers cache at hashmap key:

method=GET_user=John_Url=http://myEsiServer:8081/jahia/Jahia/pid/1

where method is the HTTP method utilized to fetch the page, user is the JahiaUser who requested thepage and Url is the request URL.

Notice that the skeleton is stored on a per-user basis, this is because the tag by default

caches skeletons (i.e. esi templates) on a per user basis. See later for an example of aclGroup

templates.

user Fragment

The ESI server then parses the HTML, detects any fragment links and, in this case, will fetchfragment 1. __esi_fragment=1&user=John identifies fragment one which is specific to user John.

Jahia returns the content of fragment 1 to the ESI server for the requesthttp://myJahiaServer:8080/jahia/Jahia/pid/1?__esi_fragment=1&user=John , in this case the string

Frag1 content. The hashmap key for this fragment is then:

method=GET_Url=http://myJahiaServer:8080/jahia/Jahia/pid/1?__esi_fragment=1&user=

John

group Fragment

If Fragment 1 had been declared as below in the JSP template:

Frag1 content

Its resulting include link in the skeleton would look like this :
http://myesiserver:8081/jahia/Jahia/pid/1http://myjahiaserver:8080/jahia/Jahia/pid/1?__esi_fragment=1&user=Johnhttp://myjahiaserver:8080/jahia/Jahia/pid/1?__esi_fragment=1&user=Johnhttp://myesiserver:8081/jahia/Jahia/pid/1


33/37

JESI QuickStart


and its ESI server hashmap key would be:

method=GET_Url=http://myJahiaServer:8080/jahia/Jahia/pid/1?__esi_fragment=1&group

=salesProjections

aclGroup Fragment


Frag1 content

If John was member of group1 and group2, its resulting include link in the skeleton would look like

this :


method=GET_Url=http://myJahiaServer:8080/jahia/Jahia/pid/1?__esi_fragment=1&aclGr

oup=group1_group2

Additionally, if Fragment 1 had been declared as below in the JSP template:

Frag1 content




oup=myMarker_group1_group2

Finally, expanding on the example above, if user John had specific rights over any content displayedinside fragment 1, then the system wouldve automatically reverted to a non-shared user-specific

version of the fragment, such that the resulting include link in the skeleton would look like this :


34/37

JESI QuickStart




oup=myMarker_John

absolute Fragment


Frag1 content



method=GET_Url=http://myJahiaServer:8080/jahia/Jahia/pid/ABSOLUTE_MARKER?__esi_fr

agment=ABSOLUTE_MARKER&aclGroup=myMarker_group1_group2

Notice how the pid and frag number are removed. This is because if this fragment is shared acrossmultiple pages, we want its hashmap key to be independent of these.

aclGroup Template/Skeleton

If the JSP template is declared as such:

Header

Frag1 content

Footer

For the user John, the skeleton is stored in the ESI servers cache at hashmap key:

method=GET_aclGroup=group1_group2_Url=http://myEsiServer:8081/jahia/Jahia/pid/1

This means that it can be shared by any user with the same rights. The resulting include links tofragments are consequently more complex, but the overall mechanism remains the same.


35/37

JESI QuickStart


16) JESI TLD

For reference, here is the current listing of the JESI TLD declaration file available in

\tomcat\webapps\jahia\WEB-INF\tld\jesi-tags.tld :

1.0

1.2jesi

JavaEdgeSideInclude(JESI)tags

fragment

org.jahia.taglibs.esi.JesiFragmentTag

> true/

expirationtrue

maxRemovalDelay

true

true

grouprtexprvalue>truetrue

true

true

org.jahia.taglibs.esi.JesiTemplateTag

JSP

Controls ESI caching characteristics of non-fragment content of thepage. description> true/

user

true

group

true

control

org.jahia.taglibs.esi.JesiControlTag

EMPTYControlsESIcachingcharacteristicsofthepage.

control

true

cache


37/37

JESI QuickStart

true

< >

true

maxRemovalDelayrtexprvalue>true

Documents

jesi tutorial