For more information about defining a ruleset, see the Portal Server Administration Guide. After creating a new ruleset, you need to define the required rules.
This section covers the following topics:
RuleSet DTD:
<?xml version="1.0" encoding="UTF-8"?> <!-- CDDL HEADER START The contents of this file are subject to the terms of the Common Development and Distribution License (the License). You may not use this file except in compliance with the License. You can obtain a copy of the License at http://www.sun.com/cddl/cddl.html and legal/CDDLv1.0.txt See the License for the specific language governing permission and limitations under the License. When distributing Covered Code, include this CDDL Header Notice in each file and include the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL Header, with the fields enclosed by brackets [] replaced by your own identifying information: "Portions Copyrighted [year] [name of copyright owner]" Copyright 2008 Sun Microsystems Inc. All Rights Reserved CDDL HEADER END --> <!-- The following constraints are not represented in DTD, but taken care programatically 1. In a Rule, All Mandatory attributes cannot be "*". 2. Only one instance of the below elements is allowed, but in any order. 1)HTMLRules 2)JSRules 3)XMLRules 3. ID should alway be in lower case. --> <!ENTITY % gtype 'GROUPED'> <!ENTITY % stype 'SCATTERED'> <!ENTITY % eURL 'URL'> <!ENTITY % eEXPRESSION 'EXPRESSION'> <!ENTITY % eDHTML 'DHTML'> <!ENTITY % eDJS 'DJS'> <!ENTITY % eSYSTEM 'SYSTEM'> <!ENTITY % ruleSetElements '(HTMLRules | JSRules | XMLRules)?'> <!ENTITY % htmlElements '(Form | Applet | Attribute | JSToken)*'> <!ENTITY % jsElements '(Variable | Function)*'> <!ENTITY % xmlElements '(Attribute | TagText)*'> <!ELEMENT RuleSet (%ruleSetElements;,%ruleSetElements;,%ruleSetElements;)> <!ATTLIST RuleSet type (%gtype; | %stype;) "GROUPED" id ID #REQUIRED extends CDATA "none" > <!ELEMENT HTMLRules (%htmlElements;)> <!ATTLIST HTMLRules type (%gtype; | %stype;) "GROUPED" id CDATA "html_rules" > <!ELEMENT Form EMPTY> <!ATTLIST Form name CDATA #REQUIRED field CDATA #REQUIRED valuePatterns CDATA "" source CDATA "*" > <!ELEMENT Applet EMPTY> <!ATTLIST Applet code CDATA #REQUIRED param CDATA "*" valuePatterns CDATA "" source CDATA "*" > <!ELEMENT JSToken (#PCDATA)> <!ELEMENT JSRules (%jsElements;)> <!ATTLIST JSRules type (%gtype; | %stype;) "GROUPED" id CDATA "js_rules" > <!ELEMENT Variable (#PCDATA)> <!ATTLIST Variable name CDATA "" type (%eURL; | %eEXPRESSION; | %eDHTML; | %eDJS; | %eSYSTEM;) "EXPRESSION" source CDATA "*" > <!ELEMENT Function EMPTY> <!ATTLIST Function name CDATA #REQUIRED paramPatterns CDATA #REQUIRED type (%eURL; | %eEXPRESSION; | %eDHTML; | %eDJS;) "EXPRESSION" source CDATA "*" > <!ELEMENT XMLRules (%xmlElements;)> <!ATTLIST XMLRules type (%gtype; | %stype;) "GROUPED" id CDATA "xml_rules" > <!ELEMENT TagText EMPTY> <!ATTLIST TagText tag CDATA #REQUIRED attributePatterns CDATA "" source CDATA "*" > <!ELEMENT Attribute EMPTY> <!ATTLIST Attribute name CDATA #REQUIRED tag CDATA "*" valuePatterns CDATA "" type (%eURL; | %eDHTML; | %eDJS; ) "URL" source CDATA "*" >
You can use * as a part of rule value except that mandatory attribute values cannot be just *. Such rules are ignored, but the message is logged in the RuleSetInfo log file. For information on this log file, see Debug File Names.
This section contains a sample rule set. The “Case Study,” on page 140 is used to illustrate how these rules are interpreted by Rewriter.
<?xml version="1.0" encoding="ISO-8859-1"?> <!-- Rules for integrating a mail client with the gateway. --> <!DOCTYPE RuleSet SYSTEM "jar://rewriter.jar/resources/RuleSet.dtd"> <RuleSet type="GROUPED" id="owa"> <HTMLRules> <Attribute name="action" /> <Attribute name="background" /> <Attribute name="codebase" /> <Attribute name="href" /> <Attribute name="src" /> <Attribute name="lowsrc" /> <Attribute name="imagePath" /> <Attribute name="viewClass" /> <Attribute name="emptyURL" /> <Attribute name="draftsURL" /> <Attribute name="folderURL" /> <Attribute name="prevMonthImage" /> <Attribute name="nextMonthImage" /> <Attribute name="style" /> <Attribute name="content" tag="meta" /> </HTMLRules> <JSRules> <!-- Rules for Rewriting JavaScript variables in URLs --> <Variable name="URL"> _fr.location </Variable> <Variable name="URL"> g_szUserBase </Variable> <Variable name="URL"> g_szPublicFolderUrl </Variable> <Variable name="URL"> g_szExWebDir </Variable> <Variable name="URL"> g_szViewClassURL </Variable> <Variable name="URL"> g_szVirtualRoot </Variable> <Variable name="URL"> g_szBaseURL </Variable> <Variable name="URL"> g_szURL </Variable> <Function name="EXPRESSION" name="NavigateTo" paramPatterns="y"/> </JSRules> <XMLRules> <Attribute name="xmlns"/> <Attribute name="href" tag="a"/> <TagText tag="baseroot" /> <TagText tag="prop2" /> <TagText tag="prop1" /> <TagText tag="img" /> <TagText tag="xsl:attribute" attributePatterns="name=src" /> </XMLRules> </RuleSet>
The general procedure to write rules is:
Identify the directories that contain the HTML pages whose content needs to be rewritten.
In these directories, identify the pages that need to be rewritten.
Identify the URLs that need to be rewritten on each page. An easy way identify most of the URLs is to search for "http" and "/".
Identify the content type of the URL: HTML, JavaScript or XML.
Write the rule required to rewrite each of these URLs by editing the required ruleset in the Rewriter service under Portal Server Configuration in the Access Manager administration console.
Combine all the rules into a ruleset for that domain.
When creating a ruleset, keep the following in mind:
The order of precedence for specific hosts is based on the longest URI match. For example for the following rulesets
mail1.central.abc.com|iplanet_mail_ruleset *.sfbay.abc.com|sfbay_ruleset *.abc.com|generic_ruleset
sfbay_ruleset is used as it has the longest match.
The rules in the ruleset are applied to each statement in the page until a rule matches a particular statement.
While writing the rules, keep in mind the order of the rules. Rules are applied to the statements in a page, in the order in which they occur in the ruleset. If you have specific rules, and general rules that contain a "*", define the specific rules first, then the general rules. Otherwise, the general rule is applied to all statements, even before the specific rule is encountered.
All rules need to be enclosed within the <RuleSet> </RuleSet> tags.
Include all rules that need to rewrite HTML content in the <HTMLRules> </HTMLRules> section of the ruleset.
Include all rules that need to rewrite JavaScript content in the <JSRules> </JSRules> section of the ruleset.
Include all rules that need to rewrite XML content in the <XMLRules> </XMLRules> section of the ruleset.
In your intranet pages, identify the URLs that need to be rewritten, and include the required rules in the appropriate sections (HTML, JSRules, or XMLRules) of the ruleset.
Assign the ruleset to the required domain.
Restart the Gateway to affect any changes:
gateway-install-root/SUNWportal/bin/gateway -n gateway-profile-name start
The ruleset root element has two attributes:
RuleSetName, for example, default_ruleset. This name is referenced in RuleSet to URI mapping.
Extends. This attribute refers to the inheritance feature of rulesets. The value points to the ruleset from which you would like to derive a ruleset.
Use the value none to signify that this new, independent ruleset does not depend on any other ruleset, or specify the <RuleSetName> to signify that your ruleset depends on another ruleset.
Rewriter uses the recursive feature to search to the end of the matched string pattern for the same pattern.
For example, when Rewriter parses the following string:
<a href="src=abc.jpg,src=bcd.jpg,src=xyz.jpg>
the rule
<Attribute name="href" valuePatterns="*src=**"/>
rewrites only the first occurrence of the pattern, which would look like this:
<a href="src=http://jane.sun.com/abc.jpg>
If you use the recursive option
<Attribute name="href" valuePatterns="REC:*src=**"/>;
Rewriter searches to the end of the matched string pattern for the same pattern, so the output would be:
<a href="src=http://jane.sun.com/abc.jpg,src=http://jane.sun.com/bcd.jpg,src=http://jane.sun.com/xyz.jpg>