Fatcoders The independent FatWire blog

Understanding Fatwire Multiple Caches

When it comes discussing the Fatwire cache,  I notices very often some confusion in customer minds. I am not very surprised of this, since  Fatwire has multiple caches and their relation is pretty complex.

In this post I will try to clarify the situation, giving  an overview that explains (almost) all of the them. I am omitting here the BlobServer cache for clarity.

The structure of the available caches is depicted  in the diagram below. Read on for an explanation.

Satellite Pagelet Cache

When you visit a Fatwire website, you normally access to one of the Satellite Servers.

In the diagram there is only one Satellite, but in a normal deployment you should have many satellite servers, ideally geographically distributed in net, and the possibly located close to your browsing location, internet-wise.

Satellite Servers are the ultimate cache in place. They cache the site, splitting web pages in pagelets. A pagelet is a piece of already rendered html. It is important to understand that a pagelet is not a whole webpage, but actually only a part of a page (think to the header, a summary, a generic block).

Pagelets are  assembled  in place by Satellite to build complete web pages. Note that because pagelets are expected to be small enough to be kept in memory, assembling of a page is expected to be very fast (no database is involved,  mostly of the cache is kept in-memory except bigger files are stored on the disk). Actually Satellite spools to disk pagelets larger than a given threshold (configurable in property files).

However Satellite does not have the ability to render templates, so when a pagelet expires or is invalidated, Satellite must grab the updated pagelet from  Content Server.

Satellite cache can be inspected using a specific tool, the Inventory servlet (using the appropriate username and password), and can be flushed using the FlushServer servlet.

Content Server Pagelet Cache

ContentServer generates pagelets on request of Satellite, executing template code (either JSP or XML). It also caches the output of the rendering, for 2 reasons:

• First reason, Satellite is optional, and Content Server can run a  site without Satellite, and must do it efficiently.
• Second reason , multiple Satellites can be  deployed, so you may need to serve the same pagelets more than once. Also a Satellite can crash, or another satellite be added, so serving pagelets must be fast as well.

ContentServer cache is  the second cache in place. You can inspect the Content Server Cache looking at the SystemPageCache database table and its attachments. The servlet to clean the content server cache is CacheServer.

Please note that when you inspect the ContentServer cache you will see the pagelets generated for satellite, however cached pagelet  for Satellite are stored in memory within satellite. So empting ContentServer cache won't clean also Satellite cache. If you want to clean also Satellite cache, that you have to do it manually.

A complete reset of the front-end cache involves both all the Satellite Servers and Content Servers.

InCache Asset Cache

So far we have seen caches that store  pagelets, that are fragments of rendered  html. Those caches works with templates having cache enabled.

However it is common to have some templates that cannot be cached. Typically this happens with certain templates that  always return a different rendering (for example, searches), and caching the output pagelet can is difficult and fundamentally pointless.

The most recent addition to the family of Fatwire caches is InCache, that basically caches the  underlying "pojos" used for rendering.  You may ask what those pojos are.

When you execute template code, you perform calls like  <asset:load  name="theAsset" ...> or <assetset:setasset  name="theAssetSet" ...> to load assets. Please note that "theAsset"  or "theAssetSet" are actually Java Objects (POJO  = Plain Old Java Objects) that will be used to render the content. Loading them is expensive because a lot of database requests may be required (or at least once, that is by far the slower operation).

Enabling InCache, those pojos are cached as well. So this cache helps to speed up the rendering of uncached templates. Indeed, the vast majority of the time is spent querying the database, and reusing already queried POJO helps a lot in speeding up also uncached templates. It also helps saving memory and reducing garbage collection.

ResultSet Cache

Last but not least, there is also the old and good cache of database queries. When you query a database, you store the result in a list in memory (in Fatwire they are generally IList, that caches the output of Java ResultSets). As long as no one accesses any more to the table from where the IList was generated, running the same query will produce the same result, so it may be cached.

Result Set cache is caching results of database queries for each query executed. ResultSet are associated to tables, so  the cached results are valid until the underlying database table changes. The result set cache is invalidated table by table whenever someone write in the database table from where content was retrieved.

This cache is helpful because ultimately all the content must be extracted by the database, but is is useful also when you write custom queries. It can be tuned editing futuretense.ini and flushed using CatalogManager servlet.

WCS Tutorial 1.6 – Gator and Flex Assets

While Xcelerate provide the basic functions for creating and editing asset, the more powerful content modeling features are powered by the component called Gator.

To better understand  which features it provides, I note that in the installer code it is still referred as CatalogCentre, while Xcelerate is referred as ContentCentre. So it looks like to be something good to build Catalogs. Actually it is.

Basically, Gator extends Xcelerate providing a rich and flexible Content Modeling feature called "Flex Assets". Apparently,  the original reason because Flex Assets were introduced was to support the implementation of ecommerce sites. It is not a coincidence that the first demo using Gatos is actually an eshop.  In fact, an e-commerce site usually requires lot of different products whose definition change often and unpredictably. Definitely, to support those requirements, Gator and its Flex Assets provide:

• ability to upgrade content model easily often, just publishing it
• a rich taxonomy, since products need to be organized in categories and subcategories
• an user interface to manipulate content definitions, not just content

Flex Assets differences from Basic Assets

We have already seen Basic Assets, so it is easier explaining how Flex Assets improve them.

First and before all, Basic Assets define assets with a descriptor  file, while Flex Assets define assets using other assets.  In fact, we don't talk normally of "flex assets" but of Flex Families, because Flex Assets are really a group (or family) of assets working together to reach a common goal.

Creating a new family will  indeed create 6 different types of assets. It can be at a first sight confusing, but  can be understood thinking that some of those assets are "structural" (define the type of the content) while only 2 of them defines actual content. Basically, structural assets replace the property descriptor file used in Basic Asset.

Second, Basic Assets define content once and for all, while Flex Assets define content in an incremental way. We have seen that for a Basic Asset you have to create a descriptor that will list properties. For Flex Assets you instead have to create attributes, that are assets too, then  you put together the asset using a Content Definition asset. An user interface is available to create attributes and assembling definitions.

This means mostly that while Basic Assets can be upgraded only recreating them from scratch or doing some alterations to the database schema, Flex Assets definition can be actually upgraded just publishing attributes and definitions.

Flex Asset hierarchies

But there is more. Using just Basic Assets you cannot directly create hierarchies (you can  only using some special coding). There are only some built-in hierarchies like the SitePlan. Flex Assets make hierarchies very easy to build using Parents,  that are always part of a new family definition. Furthermore, parents are configurable just like content, creating Parent Definitions.

When you create the content, you can place a content under a parent. Furthermore, a parent can be children of another parent, creating a tree. Using this parent-children relationship you can easily create complex hierarchies, that are very useful when the user needs to organize a large amount of content.

A parent has the special feature that all its  attributes are inherited by  its  children content. This feature is largely used to create custom hierarchies. Actually given the simplicity, is a bit unusual to find a flex family without parents, since they  are very easy to use.

Flex Families Components

So, let's recap what we have said so far. When you create a new Flex Family, you go into the Admin panel in the user interface and   see the following screen:

The Flex Family Maker  creates a number of new different types. Let's explain their meaning and use.

First, you  define a new Attribute type, Content_A in the picture. Attributes are  fields of the content,  the building blocks.

Then, you will have to create definitions to put attributes together. So basically, to define an Article with a title, an author and a body, you  have to create 3 attributes corresponding to the fields, then one Content Definition (a Content_CD asset for the family in the picture) named Article assembling the attributes you have declared. You can create different content definitions, each of them will define a different Content type.

Now finally you can create content, this means you will create an actual Flex Asset of type Content, and you will then associate one content definition, like the Article Content_CD you may have created in the previous step.

You can also create assets useful to organize content in hierarchies. This works in the same way as the content. First you create a parent definition, assembling attributes, then you can use the parent definitions to create parents. The additional step is that you can now associate content  to parent to get a hierarchy. The whole hierarchy can then be displayed in the WCS user interface. See below an example of such a hierarchy:

WCS Tutorial 1.5, AssetMaker and Basic Assets

Basic Assets

Xcelerate provides some built-in asset (an absolute requirement to build a site). However, since WCS  has a rich and flexible type system, you can define your own assets. Well, you actually should, unless you stick using sample assets, but you would lose a good deal of flexibility.

There is a lot to say about all the available possibilities to define your assets. For now, we  limit the exploration  to the features  provided by Xcelerate, namely the Basic Assets. Actually, there is a  more powerful and interesting possibility, Flex Assets, but this feature is part of Gator, that will be  described later. Furthermore,  Basic Assets are still useful although I do not recommend building a site (unless very simple and unlikely to evolve) solely on Basic Asset.

Define a new Basic Asset with AssetMaker

Let's jump start on  Basic Asset  showing an example how you can define it.

Although a bit technical as a approach (this is one of Basic Assets's drawback)  you have to describe it creating an XML file.

A very simple example of a Basic Asset descriptor looks like this:

<ASSET NAME="Simple" DESCRIPTION="Simple"  PROCESSOR="5.0"
       DEFDIR="c:\Fatwire\Shared\Storage\Simple">
  <PROPERTIES>
    <PROPERTY NAME="value" DESCRIPTION="Value">
        <STORAGE TYPE="VARCHAR" LENGTH="80"/>
        <INPUTFORM TYPE="TEXT" WIDTH="50"
          MAXLENGTH="80" REQUIRED="NO" DEFAULT="" MULTIPLE="NO"/>
    </PROPERTY>
  </PROPERTIES>
</ASSET>

What a basic asset provide

It is a simple asset, maybe the simplest possible, but this example  demonstrates what an Asset can provide.

First , as asset, like a database table, is essentially a sequence of fields, here called properties. As you can see here, each property has a storage type, so basically properties are translated in  fields of a database table.

But you can also note an important difference from database table: for each field, it is declared  how the field will be edited. In this example, you simply use a simple input text form, but with some constraints:

• width 50 characters,
• up to a maximum of 80,
• the property is not required,
• default value  is a void string.

It is however also pretty simple declare a property of type blob, that  will generate a form with a file upload. The file, once uploaded, will be stored in a folder. As you may remember we just discussed that tables may have attachments. Here we define the folder where attachments will be stored, and  thus this information is mandatory.

Basically we have seen so far how an Asset extends the concept of database table providing informations for forms editing and attachments. Actually there is more, there are many pre-defined asset fields generating various for but we will investingate on those features later. For now, just understand the concept.

Please note that Basic Assets  have however some limitation.  Most notably:

• they require coding to be defined
• they are a bit inflexible so you cannot add fields later unless you manually alter database tables
• they have limited relationship (actually provided by a feature called Association)

In the following of this tutorial we will see how those limitations has been overcome by  Flex Assets, at the price of increased complexity and lower performances (however compensated by the widespread use of caching in WCS).

WCS Tutorial 1.4, understanding Xcelerate

So far we have introduced only the basic concepts of the ContentServer layer. Basically it is the intepreter of the underlying  web programming language of WCS.But WCS is an application, and his value is mostly there. Se we  start now examining applications.

I prefer to distinguish the different underlying modules and use their internal name, because understanding which module we are talking about make easier understanding how the various modules interact. For example we will see that a Role cannot impact on ACL because the ACL belongs to the underlying layer.

Now, let's examine the first applicative layer built in ContentServer, Xcelerate.

Xcelerate

Xcelerate is the internal original name of the CMS module (at some point in the history called also CS-Direct), and it is still available today,  and is better known as  the Advanced Interface. You can still see the Xcelerate name when you log directly into the WCS advanced interface using the  URL

http://www.yoursite.com/cs/Xcelerate/LoginPage.html

Also you can see many elements named Xcelerate when you look at the ElementCatalog table.

In ContentServer we have only a concept of code. We have seen that code is actually stored as an attachment to a database table. I remember that a single piece of code, stored in a file and attached to a record in the ElementCatalog table is called Element. Basically, managing elements is the main job of ContentServer.

Xcelerate introduces a new concept, the Asset. Creating assets, managing them and providing a rich user interface for this purpose is instead the main job of Xcelerate.

What is an asset? In its simplest incarnation, an Asset can be thought as a single record in a database table. However it is not just this.  Asset can be of different types, and each asset type has their own methods for editing. So basically for each asset there are associated  forms to create and modify it.

It is important to understand that an asset is not limited to a single database table: it can actually store references to other tables. For example, the asset Template, since it allows to edit an element, is stored mainly in the Template table but it references (and allows editing) also record stored in the ElementCatalog and SiteCatalog tables. In a sense, Xcelerate provides also a user inferface for ContentServer through some specific assets.

System Assets

WCS comes bundled with a number of predefined assets. Those assets are used to implement  some standard WCS features.

As an example, let's consider the asset Page. This asset is used to build a the hierarchy of web pages in  our web sites, and there is a standard feature, called the site plan, that renders this hierarchy. We will discuss of Pages and SitePlan in greater detail  later. So far I used it only as an example of system asset. But before we move on, an important note:

A Page is NOT used to represent a single WebPage. I mean, it is wrong to assume (as many does) that you have to create a Page to render each asset as a Web Page. Page are actually used to model Sections in your site, not the complete site.

It is also immediately worth mentioning that ElementCatalog and SiteCatalog tables have a counterpart as an assets.

Basically a single entry in the ElementCatalog table can be created creating an asset CSElement, while an entry in the SiteCatalog table can be created with an asset SiteEntry. Please note that each asset has also its own table (and sometimes other additional side tables). So CSElement and SiteEntry are stored each each in 2 different tables (CSElement/ELementCatalog and SiteEntry/SiteCatalog).

We already mentioned the Template asset, that is also the more widely used asset when you build websites. This asset actually creates both an entry in the Template table but also it creates an entry in the ElementCatalog, and even one or more entries in the SiteCatalog table. So basically a template is stored at least in 3 tables: Template/ElementCatalog/SiteCatalog.

We mentioned also the Page asset, and while it is stored mainly in the table Page, but the hierarchy on pages is stored in a separate table called SitePlanTree.

So far so good providing examples  that clarify there is not an one-to-one relationship between tables and assets.

Next step will be to examine custom asset defined in Xcelerate, the so called Basic Assets.

WCS Tutorial 1.3, Content Server request processing

Before going into the details of the applications, I will explain further how Content Server processes  code, mostly to show how it differs from other web programming engine like PHP or plain JSP.

Invoking ContentServer

You invoke ContentServer with the URL

http://www.yoursite.com/cs/ContentServer

Here http://www.yousite.com/cs/ can change according your domain name and where you have installed it, but the ContentServer servlet must be always invoked, and you have also to specify some parameters. The most important parameter is pagename.

As a general rule, you can assume ContentServer?pagename=Element invokes some code, written either in CSXML or in JSP. The specific code may require more parameters to process but the parameter pagename is the one you require to invoke the code.

But before going into more details, you have to know how the code is stored inside WCS.

First, let's introduce some terminology: within WCS code is called "Element". An element is either a pieces of JSP os CSXML code. Code is stored in a file inside the file system, but cannot be accessed directly pointing to it in the filesystem, as you do in PHP and JSP.

Indeed,  there are some "metadata" associated to each element, and those metadata are stored in the database. So basically you have to read the database, and the database will tell you how to process the code.

There are 2 database tables involved : ElementCatalog e SiteCatalog. But before explaining those tables, I need to digress explaining how files in the filesystem are related to database tables.

A digression: tables with attachments

A database table for ContentServer is nothing really special, it is similar to any other table except there are a few conventions to be followed.

The first one is that every table managed by Content Server has at least the following 3 fields: "id", "name", and "description", and must be know to content server by registering it in the SystemInfo table (a special table used to index all the other tables in the system). ContentServer consistently create records with a name, assign then an id that is uniquely generated, require a name that is mandatory and offer the opportunity to store a description of the record.

Another important convention is that a table can have files  attached. But instead of storing them as blob (whose usage is pretty inconsistent between  different databases) files are actually stored in the file system, and only a pointer to the file is stored in the database table. The general convention is: when a field starts with "url" (or is just url) then its content is actually the relative path on the filesystem where is stored the file.

You may ask: relative to what? Well, as said the special table SystemInfo  stores some informations for each table. In our case, it stores the base path for files attached to each table. So basically it works this way: when you need to attach a file to a database table, you need  a field with a name starting with "url", then

1. define in the SystemInfo table a folder where files for that table will be stored
2. store in the url field the relative path name for the file
3. store the actual file in the file system, using as a file name the top level folder defined in step 1, plus  the value stored in the field as in step 3

 The ElementCatalog and the SiteCatalog tables

So you now may wonder: what has this digression has to do with the ContentServer code processing? It is simple. The code to be executed is stored in a file attached to the table ElementCatalog as just described.

You can refer to each element with its name, but the name is used to locate a record in the ElementCatalog table. ElementCatalog stores informations like last modification time, and other stuff. Then, the actual file containing the code, is an attachment to the ElementCatalog table.

Please note that using the ElementCatalog, you can invoke that code from another element using internal calls like the ics:callelement call;  but you cannot invoke the element from the servlet url with just its name in the ElementCatalog.   This is both for protection and for caching.

But it is of course still possible invoking code from the ContentServer servlet, as I explained before, using the ContentServer?pagename=Element. Hovewer, the Element heade does not refer to an entry in the ElementCatalog table, but instead to an entry in the SiteCatalog table. In the SiteCatalog table there is a field linking to the actual entry in the ElementCatalog table, which in turn points to the actual code.

SiteCatalog actually has an additional purpose: caching elements. When you invoke something from the URL, the SiteCatalog is looked up but it does not necessarily call the underlying Element it points if it has already a cached copy available. Also SiteCatalog allows  to create different entries for the same element, adding parameters for each of them, and eventually caching the output of the same element in a different ways.

How a request is actually processed

Let's recap the whole thing. This is how a content server request is actually processed:

1. the user follows a link with an url containing ContentServer?pagename=Element,  eventually with other parameters
2. the whole combination  of parameters is looked into the cache, and a suitable entry is available and (and is not expired), it is returned as a result, and the processing ends here.
3. if the requested Element has not a valid cache entry, it is looked into the SiteCatalog table and the field rootelement is used to locate the actual element in the ElementCatalog table
4. the ElementCatalog table is used in turn to locate the actual code;  field url points the the code,  concatenating its value with the top folder for this table (as specified in the SystemInfo table)
5. Now the actual code is located on disk and it is exectued; in general an element does not produce a whole web page but only a small snippet. The code can in turn invoke other elements.
6. Once the element has completed its work, the processed value is stored in the cache using informations from the SiteCatalog table
7. Finally the result of the call is returned to the end user.

Please note again this is not yet the whole story. An url assembler can be invoked before ContentServer, actually hiding the pagename=Element parameter, an apache server can be in front of ContentServer, and a remote Satellite server can be used in front of the Apache+ContentServer combo to add another layer of caching. But I will talk about  this later.

WCS tutorial, 1.2 – Understanding Content Server

We have seen that WCS is actually a layered system. Now it is time to go into the details of each layer to see which features they provide.

Content Server

The core of WCS is the Content Server layer. Although until recently the whole product has been called "Fatwire Content Server", actually  Content Server  is just the first layer. You actually call Content Server when you invoke the URL "/cs/ContentServer" (or "/servlet/ContentServer" or whatever your context path is)

ContentServer is basically an interpreter of an XML-based programming language developed before the year 2000 (presumably around 1995). It looks like the original developer wanted to implement a sort of custom ColdFusion-like  but extensible programming language. I am familiar with the idea since at the time I built something very similar.

Content Server CSXML

At the time of the initial development of WCS, the new XML standard was very young, and its purpose was a bit unclear. The obvious idea was to use XML as a programming language, and using the custom tags  programming constructs. I think so because I thought exactly the same thing.

Today I would say that it was not such a good idea mostly because XML is not really suitable to be a good programming language. I notice however that other CMS (for example, OpenCMS) works in the same way, and have a custom language based on XML.

The Content Server XML is not  generic XML, but a sort of custom programming language that I will call it, not having a better name, CSXML. Later WCS added to the CSXML  with something more standard, and more general: JSP, allowing programmers to use the more familiar Java programming language instead of a proprietary and somewhat limited programming language.

One funny thing in Content Server is that it  still uses an XML parser, written in Java but developed  by Microsoft! If you look to the jars in the WCS installation, you can still find the MSXML.jar. There was a time when Microsoft was Java friendly (they licensed Java  and  developed a version of Java for Windows for a while). Then they moved on... and C# is another story.

When XML came out, Microsoft  developed one of the first XML parsers,  an open source one, and it is the parser that still today ContentServer uses to parse his CSXML.  Please note that the MSXML parser is not even standard compliant since it was developed before there was actually a standard for XML, and it has some oddities. It is not validating, and it has tag names  case insensitive , but  attributes are case sensitive...

CSXML is extensible, in the sense that you can develop custom tag libraries and invoke a tag. It is widely used  in WCS since large part of the Xcelerate and Gator layers are developed in CSXML. You also need to use  CSXML when you want to customize the interface.

Actually not everything in Content Server is implemented in CSXML. CSXML is a sort of scripting language to implement the user interface but all the underlying logic (especially the database access logic)  is actually implemented in Java, packaged in jars and called through tag libraries. There are many tag libraries and only a  fraction of them is actually documented for site development purposes.

Content Server JSP

CSXML is not the only way to develop for Content Server. There is also another, more standard, programming language available: I mean  plain simple (and standard) JSP. So basically you have the choice of using CSXML to code your site and customizations, or use standard JSP (that of course allows you also to code the logic in pure and simple Java).

However, ContentServer is not just a plain JSP interpreter. It provides a lot of other services, that in CSXML are accessible through custom tags. The same is true also for JSP. The smart idea is that every tag defined for XML  is available as a custom tag library for the JSP, with the same name and the same attributes.

So for example you can load an asset in CSXML using

<ASSET.LOAD TYPE="..." OBJECTID="..."/>,

bug you can do the same in a JSP using

<asset:load type="..." objectid="..."/>

Of course it is not just that in JSP you can use asset:load while in CSXML you use ASSET.LOAD. There are many other differences, in JSP you can use scriptlets, expressions like <%= ... %> and  <% ... %>,  while in CSXML you cannot, and you have to use a string replacement mechanism provided by CSXML for variables. For simpler things you can use CSXML but it becames easily too limiting. I am not going to go into the details however, since I consider CSXML leagacy and I will focus mostly on JSP.