This chapter explains WebCenter Sites URL assemblers, which manage URL assembly and disassembly, and provide an interface that you can use to define the appearance of URLs.
This chapter contains the following sections:
URL assemblers, in conjunction with URL generation tags, are used to generate WebCenter Sites URLs and to disassemble the URLs they generate.
This section contains the following topics:
WebCenter Sites URL generation tags (<satellite.link>, <satellite.blob>, <render.getpageurl>, <render.getbloburl>, <render.satelliteblob>, <rendergettemplateurl>) are used to construct a link to a WebCenter Sites resource, such as a page or a blob. The data, such as tag attributes and nested argument tags which you specify when using the tag, is converted into an abstract object called a URL definition. The URL definition is passed into the URL assembler. The URL assembler then converts the definition into a string URL that is returned.
Two assemblers are installed with WebCenter Sites, but you have the option of creating your own assemblers in order to directly control the appearance of your URLs. Before you can use the assemblers you create, you must first register them with WebCenter Sites.
The assembler that is configured as the default is used to create all WebCenter Sites URLs. You can change the default assembler. You can also override the use of this default assembler in individual link tags.
Because an assembler can create a URL in any form that the assembler's author dictates, it may be impossible for the URL to be decoded into parameters by an application server when an assembled link is requested. For decoding to take place, the assembler must be able to disassemble the string URL into its definition. Assemblers are therefore reversible, that is, capable of disassembling any URLs that they assembled.
If a URL has been created using an assembler other than the default assembler, then the default assembler cannot disassemble the URL. At that point, the next highest ranked assembler attempts to disassemble the URL. If it succeeds in creating a definition, then the assembler engine is said to have discovered its assembler, and the definition is converted into parameters for processing. If the next highest ranked assembler fails to disassemble the URL, the third highest ranked assembler is called upon to disassemble it. This process continues until the URL is successfully disassembled. Note that this process requires an assembler to be able to recognize the URLs it assembled as its own, and all other URLs as foreign.
See Section 45.3.1, "Creating Assemblers" and Section 45.3.2, "Registering and Ranking Assemblers" for more information about creating, registering, and ranking assemblers.
URL assemblers are only invoked on GET requests. They are not invoked on POST requests. For example, when accessing a page with a GET request, the URL assembler is invoked to disassemble the URL. It then provides the appropriate parameters that WebCenter Sites requires to open that page (such as c, cid, and pagename) by adding them to the definition (if they do not already exist in the definition). However, when a request is POSTed, such as a form with method=post, the URL assembler is not invoked to disassemble the URL. Therefore, the parameters WebCenter Sites requires to open the page must be part of the post request itself.
This can be accomplished by encoding the following tag into the page's template or element (replacing the sample values with the parameters WebCenter Sites requires for the page's URL):
<satellite:form method="post" id="assetid">
<render:gettemplateurlparameters list="args" ... /><!-- add all parameters that are normally part of a URL -->
<ics:listloop listname="args">
<input type="hidden" name="<string:stream list="args" column="name"/>" value="<string:stream list="args" column="value"/>"/>
</ics:listloop>
The two assemblers that are installed with WebCenter Sites are Query Assembler and QueryAsPathInfo Assembler.
This section contains the following topics:
The Query Assembler creates URLs with query strings. It is the default assembler, and it is automatically registered in WebCenter Sites. Therefore, until you make any modifications (such as changing the default assembler or overriding the default in link tags), Query Assembler will be used to generate all URLs.
The QueryAsPathInfo Assembler does not use query strings. Instead, the QueryAsPathInfo Assembler encodes the query string and appends it to the end of the servlet name. The benefit of this assembler is that it creates URLs that can be indexed by search engines. The QueryAsPathInfo Assembler is not automatically registered with WebCenter Sites.
Note:
A sample URL assembler implementation ships with the FirstSiteII sample site. The source code is located on the WebCenter Sites CD:
/ContentServer/FirstSiteII/PrettyURL/src/com/fatwire/firstsite/uri/FSIIAssembler.java
Additional information is available in the Oracle Fusion Middleware WebCenter Sites Java API Reference. The classes of interest are:
Definiton
Definiton.AppType
Definiton.ContainerType
AbstractAssembler
AbstractAssembler.AssemblyContext
AbstractAssembler.DisAssemblyContext
Assembler
DisAssembler
It may also be beneficial to set up a debug environment with FSIIAssembler.java so that you can step through the code.
This section explains how to create and register your own assemblers. This section also explains how to modify link tags to override the use of the default assembler.
This section contains the following topics:
The WebCenter Sites URL Assembly module enables you to create your own assemblers. This option gives you direct control of the appearance of your URLs.
Write a java class that implements the com.fatwire.cs.core.uri.Assembler interface. For information about this class, see the Oracle Fusion Middleware WebCenter Sites Java API Reference.
Compile the class into a .jar file.
Deploy your class into the WebCenter Sites web application and the web application for each remote Satellite Server you have installed.
This usually means copying the .jar file you just created into your web application's WEB-INF/lib folder. For remote Satellite Servers, this means copying it to the resin/webapp/ROOT/WEB-INF/lib folder.
Register your new assembler in the ServletRequest.properties file on both WebCenter Sites and all of your remote Satellite Servers (see Section 45.3.2, "Registering and Ranking Assemblers" if you need instructions).
Restart WebCenter Sites and all of your remote Satellite Servers.
Before an assembler can be used to create URLs, it must first be registered with WebCenter Sites. The registration is done by listing assembler class names with corresponding short forms in a property file. The registration also includes a ranking that indicates in which order the assemblers should be used.
Invoke the Property Editor.
Open the ServletRequest.properties file.
Click the URI Assembler tab to access the assembler properties.
Specify the classname and shortform of the assembler you want to register.
The third element in the property name indicates the ranking of the assembler. The assembler with the ranking of 0 is the highest ranked (and default) assembler, the assembler with the ranking of 1 is the next highest ranked, and so on.
If you want to configure the new assembler to be the default assembler, enter the classname and shortform values in the properties that have 1 as their ranking.
For example, the syntax to register the QueryAsPathInfo assembler as the default assembler would be as follows:
Table 45-1 Assembler Properties
| Property Name | Property Value |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
query |
Note:
Make sure that the Query Assembler is always registered, even if you have lowered its ranking. The Query Assembler must be registered with the shortform value of query.
Depending on the ranking of the new assembler, you may need to adjust the rankings of the other assemblers. Verify that all of the assemblers are configured and ranked correctly in the property file. If they are not, make any necessary changes.
Choose File, then Save to save your changes and close the Property Editor.
Repeat steps 1 through 2 for each remote Satellite Server you have installed.
Restart WebCenter Sites and all of your remote Satellite Servers.
WebCenter Sites link tags can be modified to use an assembler other than the default assembler. The link tags accept an attribute, assembler, which take an assembler short form as a value.
For example, to override the default assembler with the QueryAsPathInfo assembler in an individual link tag, the syntax would be as follows:
<satellite:link pagename=example assembler=pathinfo />
If an asset has a vanity URL for the template passed in the name argument, then the tag returns a vanity URL. If the asset does not have a vanity URL, then the tag returns the Sites URL. The <render:gettemplateurl> tag can be used to generate a vanity URL link. Thus any redirected URL will always return the vanity URL if present. That way if an existing link is accessed (for example, from a bookmark), all subsequent URLs will be vanity URLs.
To generate a vanity URL for a specific WebRoot, an additional optional parameter called hostparam should be passed to render: gettemplateurl. The value of the hostparam should match the hostname attribute of WebRoot. This can be used to generate a link to another website or subdomain within the same website.
<render:gettemplateurl outstr="pageURL" hostparam=<hostname of the WebRoot asset> tname='<%=ics.GetVar("template")%>' args="c,cid" />