| Oracle® Access Manager Developer Guide 10g (10.1.4.2.0) Part Number E10355-01 |
|
|
View PDF |
| Oracle® Access Manager Developer Guide 10g (10.1.4.2.0) Part Number E10355-01 |
|
|
View PDF |
This appendix provides overviews of XML, XML schemas, and XSLT, for those who may need it in order to follow the discussion and examples for these topics in the main chapters of this Guide. Topics in this appendix include:
XML stands for Extensible Markup Language. It is a set of rules that define tags that break a document into parts and identify the parts of the document. These tags define a syntax that can then be used, in combination with an XSL stylesheet, to reconstruct the document.
The tags that are defined must follow the XML rules, but their content and arrangement can be anything the developer wants. A file of XML text, arranged to represent a certain document, is called an XML application. Oracle Access Manager's OutputXML is an XML application, designed to create HTML which will in turn present Identity System pages to a browser.
Oracle Access Manager also uses XML as a structured way to provide some parameters that control its operation. This is a different use than for OutputXML, but since the applications are much shorter and the XML syntax rules are followed here as well, one of these files will serve as an example. For example, frontpageadminparams.xml has the following content:
<?xml version="1.0" ?>
<ParamsCtlg xmlns="http://www.oblix.com"
CtlgName="frontpageadminparams">
<CompoundList ListName="">
<SimpleList>
<NameValPair ParamName="top_frame"
Value="_top" />
<NameValPair ParamName="top_main_frame"
Value="main_frame" />
<NameValPair ParamName="min_location_area"
Value="400" />
</SimpleList>
</CompoundList>
</ParamsCtlg>
This indented presentation, showing the tag levels, is an automatic feature of Microsoft's Internet Explorer. XML editors will also show the file in this way.
Some important parts of this file are the following:
<?xml version="1.0" ?>
This, the XML declaration, is the first line of any well-formed XML application. Internet Explorer and some editors will not show the file as formatted XML unless this line is present. The starting and ending ? make this an XML processing instruction. version="1.0" is an attribute. Attributes are name-value pairs separated by an equals sign, which provide additional information for the instruction. Currently there is only one version of XML.
<ParamsCtlg xmlns="http://www.oblix.com" CtlgName="frontpageadminparams">
<ParamsCtlg> is a tag, which starts the definition of the first element in the XML application. The definition ends with the matching closing tag, which has the same form except it uses a / before the tag name:
</ParamsCtlg>
Everything between the starting and ending tags defines the element ParamsCtlg. Nested within it is the element CompoundList, which has elements nested within it, and so on. An important attribute is xmlns, which stands for XML namespace.This specifies an owner and possible reference source for this XML application. We identify ourselves as creators of this application.
The technically precise way to write this element would have been
<NameValPair ParamName="top_frame" Value="_top" /> <NameValPair> ParamName="top_frame" Value="_top" </NameValPair>
However, when the definition is a short one like this, the XML rules allow use of an abbreviated closing tag. /> indicates the closing tag for the immediately preceding start tag.
The attributes ParamName="top_frame" and Value="_top" provide the useful content of the file, which is the name of a variable used by Oracle Access Manager and its value.
An important concept, essential to the application of stylesheets, is a node. A node is a level within the XML application, described by stringing together the elements that locate it uniquely within the nested elements. For example, ParamsCtlg is the root node for the application. The root node is the element name immediately following the XML processing instruction(s); all other elements are nested within it. Other examples of nodes are ParamsCtlg/CompoundList and ParamsCtlg/CompoundList/SimpleList.
An XML Schema shows and describes the content of an XML application. The following list interprets some of the elements that appear within a schema definition file, based on the first few characters of each element. This is not intended to be an explanation of the full XML Schema syntax; see the referenced site for that.
xsd:attribute : Appears within the body of an element being defined, and defines an attribute that belongs to it. Parts of the definition usually present are:
name="xxxx": The name of the attribute
type="yyyy": The data type for the attribute; see the following list.
use="required": This is present only if the attribute must be present in the output.
value="zzzz": This is present only if the attribute takes a fixed value.
xsd:choice: Precedes a list of other elements, indicating that one and only one of those elements is allowed. The choice itself can be made from zero to many times, as controlled by the values of minOccurs and maxOccurs. The value of minOccurs is the fewest number of times this element can appear in the list. If the value is zero, the element is optional in the list. The value of maxOccurs is the greatest number of times the element can appear in the list. A value of Unbounded means there is no limit.
xsd:complexType: Most often used in the body of an element that is being defined, and means that the element will contain other elements.
xsd:element name="xxxx": Declares and within its body goes on to fully define a category of information describing the element xxxx. Most instances of this in the schema files go on to provide a body for the element and build it up from subelements. A few, for example ObTextMesage in the displaytype.xsd file, have no body, in which case they use type to immediately specify the data type of the element.
xsd:element ref="xxxx": Most often used to provide the name of a subelement for inclusion in a list that is part of the body defining an element. The referenced element will have been defined elsewhere. The element may also include the attributes minOccurs and maxOccurs.
xsd:enumeration: Provides a list of possible values.
xsd:include schemalocation="xxxx": An element that specifies a file which contains additional XML schema information, to be treated just as if it were provided inline in the current file.
xsd:restriction base="xxxx": Defines the pattern for values that are used for a data type being defined; see xsd:simpletype. Oracle Access Manager uses the restriction base NMTOKEN, which means the value must be a legal XML string and contain no white spaces.
xsd:sequence: Precedes a list of subelements within another element, and indicates that, if they are present, they will appear in the order listed.
xsd:simpletype: This begins the definition of a data type, usually followed by an xsd:restriction definition.
Some possible data types are:
xsd:boolean: Acceptable values are true/false, or 1/0.
xsd:date: Acceptable values are dates in the form YYYY-MM-DD (many other date types are possible).
xsd:decimal: Acceptable values are decimal numbers (other number types are possible)
xsd:string: Acceptable values are a string of characters
xsd:time: Acceptable values are a time of day in the form hh:mm:ss.sss.
xsd:uri-reference: Acceptable values are URLs.
All of the Oracle XML schemas are defined within a root element called oblix. The following table shows the schema for the usc_profile.xsd definition of oblix, beginning with its initial definition in component_profile.xsd. The table shows the schema only to the first two node levels under oblix; the full schema goes much deeper. If you look at just the pure OutputXML provided by the Identity System for the view (My Identity) program, this information, in this order, is what you see.
| Level 1 | Level 2 |
|---|---|
ObProfile (defined in component_profile.xsd) |
ObPanel |
ObHeaderPanel |
|
ObRequestInfo |
|
ObScripts |
|
ObForm |
|
ObDisplay |
|
ObTextMessage |
|
ObButton |
|
ObStatus |
|
ObNavBar (defined in navbar.xsd) |
ObRequestInfo |
ObScripts |
|
| ObMisc | |
ObApps |
|
ObApplication |
|
ObFunctionsButtons |
|
ObStatus |
|
ObSearchForm (defined in searchform.xsd) |
ObHelpContext |
ObRequestInfo |
|
ObScripts |
|
ObForm |
|
ObDisplay |
|
ObButton |
|
ObAdvancedSearch |
|
ObSearchRow |
|
ObStatus |
|
ObApplicationFunc (defined in navbar.xsd) |
ObFunctions |
ObRequestInfo |
|
ObStatus |
|
ObStatus (defined in component_basic.xsd) |
This is a string of type xsd:string; it contains no other elements. |
XSL stands for Extensible Style Language. Files written in this language are used along with XSLT to create documents. The XSL file itself is a well-formed XML document. The language relies heavily upon the use of templates, which are sets of instructions to the XSL transformer, telling it what to produce as output for a particular node within the XML.
XSLT stands for XSL Transformation. This is a process that combines an XML application with an XSL stylesheet to create a document.
The following list interprets some of the elements that appear within an Identity System style sheet file, based on the first few characters of each element. This is not intended to be an explanation of the full XSLT syntax; see the referenced site for that.
Note:
In XSL files, lines starting with <xsl: are instructions to the XSL transformer. All others are HTML text to be written verbatim into the HTML output.xsl:apply-templates select="xxxx" : Once the transformer is positioned to a node within the XML, using xsl:template-match, this element identifies which subnodes or sub-subnodes are to be processed. Point at sub-subnodes within the selected node by providing their nested structure, for example xsl:apply-templates="xxxx/yyyy", where yyyy is a node nested within xxxx. If the select option is omitted, templates for all the subnodes under the matched node are processed.
The transformer decides which templates to use by identifying each subnode by name, and then searching the entire stylesheet for the best xsl:template match for that name. The match will generally be on the last node in the nested list, for example yyyy in the previous example. The instructions for that matched node are applied immediately.
xsl:attribute name="string" : Inserts the text specified by string into the output.
xsl:call-template name="xxxx" : Immediately performs the transformation required by the template xxxx. The template to be called will have been specified using xsl:template name="xxxx".
xsl:choose : Precedes a list of possible transformations, each of which is indicated by the use of the xsl:when element. It may be that none of the xsl:when elements applies; the xsl:otherwise element covers this possibility. If more than one of the xsl:when elements is true, only the first true xsl:when element is applied.
xsl:for-each select="xxxx" : Applies the content of this element to all occurrences of xxxx.
xsl:if test="expression" : Permits a choice to be made. If expression evaluates to a Boolean true, the content of the xsl:if element is performed. If not, it's not performed. Expression syntax is described in the following paragraphs.
xsl:include href ="xxxx": An element that specifies a file which contains additional XSL stylesheet information, to be treated just as if it were provided inline in the current file.
xsl:number value="expression" : Used to insert a formatted integer into the output. In Identity System stylesheets, expression often uses the position() function, which indicates the position of a node in a list, starting with 1.
xsl:otherwise : The last element in the list of elements under an xsl:choose, following the xsl:whens, which is to be applied if none of the xsl:whens is true.
xsl:template match="xxxx" : Point the transformer to the node named xxxx in the XML data. Point at subnodes by providing their nested structure, for example xsl:template-match="xxxx/yyyy", where yyyy is a node nested within xxxx. This must be followed by one or more uses of xsl:apply-templates, otherwise no transformation of the XML data will be done.
xsl:template name="xxxx" : Create a named template, to be applied when xsl:call-template="xxxx" is used.
xsl:value-of select="expression" : Inserts the value specified by expression into the output.
xsl:when test="expression" : Permits a choice to be made. If expression evaluates to a Boolean true, the content of the xsl:when element is performed. If not, it's not performed. Usually, multiple xsl:when elements are nested under an xsl:choose element.
Again, this is only a subset of a much longer list, provided to allow you to interpret Oracle Access Manager XSL files. Expressions can be of several kinds:
Node Sets
A node set describes a set of nested elements, in the form xxxx/yyyy/zzzz, meaning the element zzzz is nested within the element yyyy which is then nested within the element xxxx. When a node set is used as the expression for a test, the test is true if the nested set exists in the XML, false if it does not.
Further, this may be used in the form xxxx/yyyy/zzzz[@attribute = a value]. This means to look at the value of the attribute belonging to element zzzz. The expression is true if the attribute has the specified value and false otherwise.
String Content
One form of this is
<xsl:value-of select="@attribute" />
which means return the value of the attribute.
Another is
<xsl:if test="@attribute">
which is true if the attribute is valid for the element and has a non-NULL value.
Numeric Content
In this case, the expression reduces to a number. An example is
<xsl:number value="position()-1">
which gives a number one less than the position of the current element in a list of elements.
Client-side processing of stylesheets is supported only with Microsoft Internet Explorer (IE) 5.0 and later. Earlier versions of IE require installation of a patch..
To set up client side processing
Install the latest msxml patch.
Install the registration tool for msxml.
This can be obtained from:
http://msdn.microsoft.com/msdn-files/027/001/469/xmlinst.exe
Enter the following command sequence:
xmlinst -u regsvr32 -u msxml.dll regsvr32 msxml3.dll xmlinst
Change the controlling parameter.
In the $Identity_install_dir/apps/common/bin/globalparams.xml parameter file, change the value for OutputFormat from default to xml.
Restart the Identity Server.
Verify the change.
To verify that this change indeed took place, enter the Identity System using an Internet Explorer 5 browser.
If you do a view source, you will see XML instead of HTML.
Oracle Access Manager has a built in XSL Transformation processor. This processor implements most, but not all, of the XSLT standard. The following is some information applying to the current version.
The processor does not automatically insert the declaration line:
<?xml version="1.0" ?>
in XML files that it generates. If this is needed because you want to see an indented XML presentation, you must include it in the stylesheet.
The processor does not support UTF characters in a sort. An attempt to do this will generate an error report.
The processor has a stack limit depth of 5298; recursive templates can go no deeper than this.
The processor assumes that its output is intended for use by a browser and therefore formats output with an HTML formatter.
The processor is intended primarily for use in a production environment, where performance is important. For this reason, it does only minimal checking of stylesheet syntax. Very bad syntax can cause the processor to fail. For this reason, only known stylesheets with validated content should be used in the production environment. Some validation tools are listed in the Oracle Access Manager Customization Guide.
Embedded stylesheets in the XML are not supported.
Full support, or in some cases, any support, of the following commands is not provided. If you need to use these commands, double-check your results before putting the stylesheet into production.
XSL:format-number
XSL:output
XSL:document
XSL:namespace
XSL:comment
XSL:format
XSL:processing instruction
XSL:sort: case order
XSL: id
Full descriptions and specifications for this information are available at:
See the information under XML, XML Schema, and XSL
You can find documentation for XML at:
You can find documentation for XML Schema at:
A tutorial on the XML schema syntax is available at:
http://www.w3.org./TR/xmlschema-0
You can find documentation for XSL and XSLT at:
