froehlich 02/01/30 08:45:40 Modified: src/documentation/xdocs/developing deli.xml Log: applied patch from Butler, Mark [[EMAIL PROTECTED]] Revision Changes Path 1.4 +119 -92 xml-cocoon2/src/documentation/xdocs/developing/deli.xml Index: deli.xml =================================================================== RCS file: /home/cvs/xml-cocoon2/src/documentation/xdocs/developing/deli.xml,v retrieving revision 1.3 retrieving revision 1.4 diff -u -r1.3 -r1.4 --- deli.xml 22 Jan 2002 01:32:22 -0000 1.3 +++ deli.xml 30 Jan 2002 16:45:40 -0000 1.4 @@ -27,7 +27,8 @@ as a profile repository, along with a list of differences specific to this particular client. The process of reassembling the final profile from the profile references and differences is known as profile resolution.</p> - <p><link href="http://www-uk.hpl.hp.com/";>HP Labs</link> + <p> + <link href="http://www-uk.hpl.hp.com/";>HP Labs</link> has produced an open-source library called DELI that allows Java servlets to resolve HTTP requests containing CC/PP or UAProf information and query the resolved profile. This document describes how DELI may be used @@ -47,19 +48,11 @@ <link href="http://www.w3.org/TR/2000/WD-CCPP-ta-20000721/";>CC/PP Terminology and Abbreviations</link>. A CC/PP profile is broadly constructed as a two level hierarchy: a profile has a number of components and each component has a number -of attributes. A proposed -(and largely deprecated) protocol for CC/PP is described in -<link href="http://www.w3.org/TR/NOTE-CCPPexchange";>CC/PP exchange protocol using HTTP extension framework</link> and -<link href="http://search.ietf.org/internet-drafts/drafts-hjelm-http-cnhttp-scenarios-00.txt";>Content Negotiation Header in HTTP Scenarios</link>. -The protocol work has been -deprecated because the CC/PP Working Group was not chartered by -the W3C to do protocol work. In addition this protocol uses -<link href="http://www.w3.org/Protocols/HTTP/ietf-http-ext/";>HTTP-ex</link> which means it -is incompatible with existing HTTP web servers. Therefore it is suggested that -people requiring CC/PP functionality should use the W-HTTP protocol -used by UAProf. This has identical functionality to the deprecated CC/PP protocol based on HTTP-ex, but -will work with existing HTTP servers. Hopefully when the CC/PP Working Group is recharted to work -on protocols, it will propose a protocol compatible with HTTP/1.1 similar to W-HTTP.</p> +of attributes. A protocol for transmitting CC/PP profiles has been +<link href="http://www.w3.org/TR/NOTE-CCPPexchange";>proposed</link> but is based on an experimental +variant of HTTP known as <link href="http://www.w3.org/Protocols/HTTP/ietf-http-ext/";>HTTP-ex</link> so is not compatible with existing servers. +Therefore DELI uses the W-HTTP protocol proposed by UAProf. This has identical functionality to the CC/PP +protocol based on HTTP-ex, but is compatible with HTTP/1.1.</p> </s1> <s1 title="UAProf"> <p>The UAProf specification is based on the CC/PP specification. Like CC/PP, @@ -68,43 +61,51 @@ - a specific set of components and attributes - to describe the next generation of WAP phones. The specification also describes two protocols for transmitting the profile -from the client to the server. Currently DELI only supports one of the UAProf -protocols, as the other is based on HTTP-ex so is incompatible with existing -web servers. </p> - <p>Profiles using the UAProf vocabulary consist of six components: +>from the client to the server. Currently DELI only supports the W-HTTP protocol.</p> + <p>Profiles using the UAProf vocabulary consist of six components: HardwarePlatform, SoftwarePlatform, NetworkCharacteristics, BrowserUA, WapCharacteristics and PushCharacteristics. These components contain attributes. In DELI each attribute has a distinct name and has an associated collection type, attribute type and resolution rule. In UAProf there are three collection types:</p> - <ul> - <li><code>Simple</code> contains a single value e.g. ColorCapable in HardwarePlatform. </li> - <li><code>Bag</code> contains multiple unordered values e.g. BluetoothProfile in the + <ul> + <li> + <code>Simple</code> contains a single value e.g. ColorCapable in HardwarePlatform. </li> + <li> + <code>Bag</code> contains multiple unordered values e.g. BluetoothProfile in the HardwarePlatform component.</li> - <li><code>Seq</code> contains multiple ordered values e.g. Ccpp-AcceptLanguage + <li> + <code>Seq</code> contains multiple ordered values e.g. Ccpp-AcceptLanguage in the SoftwarePlatform component.</li> - </ul> - <p>In addition attributes can have one of four attribute types:</p> - <ul> - <li><code>String</code> e.g. BrowserName in BrowserUA.</li> - <li><code>Boolean</code> e.g. ColorCapable in HardwarePlatform.</li> - <li><code>Number</code> is a positive integer e.g. BitsPerPixel in HardwarePlatform.</li> - <li><code>Dimension</code> is a pair of positive integers e.g. ScreenSize in HardwarePlatform.</li> - </ul> - <p>Finally attributes are associated with a resolution rule:</p> - <ul> - <li><code>Locked</code> indicates the final value of an attribute is the first + </ul> + <p>In addition attributes can have one of four attribute types:</p> + <ul> + <li> + <code>String</code> e.g. BrowserName in BrowserUA.</li> + <li> + <code>Boolean</code> e.g. ColorCapable in HardwarePlatform.</li> + <li> + <code>Number</code> is a positive integer e.g. BitsPerPixel in HardwarePlatform.</li> + <li> + <code>Dimension</code> is a pair of positive integers e.g. ScreenSize in HardwarePlatform.</li> + </ul> + <p>Finally attributes are associated with a resolution rule:</p> + <ul> + <li> + <code>Locked</code> indicates the final value of an attribute is the first occurrence of the attribute outside the default description block.</li> - <li><code>Override</code> indicates the final value of an attribute is the last occurrence + <li> + <code>Override</code> indicates the final value of an attribute is the last occurrence of the attribute outside the default description block.</li> - <li><code>Append</code> indicates the final value of the attribute is the + <li> + <code>Append</code> indicates the final value of the attribute is the list of all occurrences of the attribute outside the default description block.</li> - </ul> - <p>The UAProf vocabulary is described using the file <code>uaprofspec.xml</code>. + </ul> + <p>The UAProf vocabulary is described using the file <code>uaprofspec.xml</code>. This describes the attribute name, component, collectionType, attributeType and resolution rule of each component. The vocabulary description file has the following format:</p> - <source><![CDATA[ + <source><![CDATA[ <?xml version="1.0"?> <vocabspec> <attribute> @@ -116,11 +117,17 @@ </attribute> </vocabspec> ]]></source> - </s1> - <s1 title="W-HTTP Protocol"> - <p>An + <p>DELI can also read vocabularies described using RDF schemas. The WAP Forum have + published two such schemas to describe the two versions of UAProf currently in use. However + RDF Schema does not provide an easy way of describing attributeType or resolution rule. + Therefore the UAProf schemas store this information in the comments field for each attribute. + Therefore DELI also parses the comments fields to create the vocabulary. This is not an ideal + solution so hopefully a more robust way of representing this information will be used in later versions of UAProf.</p> + </s1> + <s1 title="W-HTTP Protocol"> + <p>An example W-HTTP request using this protocol is shown below:</p> - <source><![CDATA[ + <source><![CDATA[ GET /ccpp/html/ HTTP/1.1 Host: localhost x-wap-profile:"http://127.0.0.1:8080/ccpp/profiles/test09defaults.rdf";, @@ -141,21 +148,21 @@ </rdf:Description> </rdf:RDF> ]]></source> - <p>The first two lines + <p>The first two lines describe the resource that is being requested by the client, http://localhost/ccpp/html, and the method being used to make the request, GET, and the protocol being used HTTP/1.1. The remaining lines of the request describe the device delivery context. This is specified using a profile reference and a profile-diff. The profile is referenced via the x-wap-profile line and has the URI</p> - <source><![CDATA[ + <source><![CDATA[ http://127.0.0.1:8080/ccpp/profiles/test09defaults.rdf. ]]></source> - <p>After the profile reference, there is a value</p> - <source><![CDATA[ + <p>After the profile reference, there is a value</p> + <source><![CDATA[ 1-Rb0sq/nuUFQU75vAjKyiHw== ]]></source> -<p>known as a profile-diff digest. + <p>known as a profile-diff digest. The first part of the profile-diff-digest, 1-, is the profile-diff sequence number. This is used to indicate the order of the profile-diffs and to indicate which profile-diff the profile-diff @@ -168,7 +175,7 @@ The <link href="http://www.faqs.org/rfcs/rfc2045.html";>Base64 algorithm</link> takes as input arbitary binary data and produces as output printable encoding data.</p> - <p>After the profile-diff digest, the next line contains the + <p>After the profile-diff digest, the next line contains the x-wap-profile-diff. This request header field also has a profile-diff sequence number which indicates that this profile-diff corresponds to the previous @@ -177,55 +184,65 @@ request header fields are permitted by the HTTP/1.1 specification as long as each subsequent line starts with either a tab character or a whitespace. </p> - <p>When the server receives a HTTP request with UAProf + <p>When the server receives a HTTP request with UAProf request headers, it has to perform profile resolution i.e. retrieve the referenced profile(s) and any further profiles referenced via default blocks. It then has to merge these profiles and the profile-diffs while applying the UAProf resolution rules.</p> - </s1> + </s1> <s1 title="Configuring DELI"> -<p>In order to use DELI, you need to enable the DELI component. -In addition, you may want to configure DELI using <code>deliCocoonConfig.xml</code>, the DELI + <p>In order to use DELI, you need to enable the DELI component. +In addition, you may want to configure DELI using <code>deliConfig.xml</code>, the DELI configuration file or <code>legacyDevices.xml</code>, the DELI legacy device support file.</p> -<s2 title="Cocoon.xconf"> + <s2 title="Cocoon.xconf"> <p>In order to use DELI you need to specify the configuration file and set the <code>use-deli</code> parameter to true. You can either do this in <code>deli.xconf</code> in which case you will need to rebuild Cocoon or change the deployed <code>cocoon.xconf</code> in the web-server directory:</p> <source><![CDATA[ <deli> - <parameter name="deli-config-file" value="deliCocoonConfig.xml"/> + <parameter name="deli-config-file" value="resources/deli/config/deliConfig.xml"/> <parameter name="use-deli" value="true"/> </deli> ]]></source> -</s2> -<s2 title="Sitemap.xmap"> - <p>The file <code>sitemap.xmap</code> is already configured to provide a TraxTransformer for -use with DELI called <code>xslt-deli</code>: + </s2> + <s2 title="Sitemap.xmap"> + <p>In order to make profile information available to your stylesheet then you + need to add <code><![CDATA[<map:parameter name="use-deli" value="true"/>]]></code> to the + match that specifies your stylesheet in <code>sitemap.xmap</code>. Here is the match used for the deli test stylesheet: </p> <source><![CDATA[ - <map:transformer name="xslt-deli" logger="sitemap.transformer.xslt" - src="org.apache.cocoon.transformation.TraxTransformer" - pool-max="32" pool-min="16" pool-grow="4"> - <use-request-parameters>false</use-request-parameters> - <use-browser-capabilities-db>false</use-browser-capabilities-db> - <use-deli>true</use-deli> - </map:transformer> + <map:match pattern="deli.html"> + <map:generate src="docs/samples/hello-page.xml"/> + <map:transform src="stylesheets/deli_test.xsl" type="xslt"> + <map:parameter name="use-deli" value="true"/> + </map:transform> + <map:serialize type="html"/> + </map:match> ]]></source> -</s2> -<s2 title="Main Configuration File"> -<p>DELI also has its own -configuration file has the following format:</p> + </s2> + <s2 title="Main Configuration File"> + <p>DELI also has its own +configuration files that are found in the <code>resources\deli\config</code> directory. +The most important one, <code>deliConfig.xml</code> is used to configure the main DELI options:</p> <source><![CDATA[ <?xml version="1.0"?> <deli> + <legacyDeviceFile>resources/deli/config/legacyDevice.xml</legacyDeviceFile> <debug>false</debug> <printDefaults>false</printDefaults> <printProfileBeforeMerge>false</printProfileBeforeMerge> - <legacyDeviceFile>legacyDevice.xml</legacyDeviceFile> - <vocabularyFile>uaprofspec.xml</vocabularyFile> + <schemaVocabularyFile namespace="http://www.wapforum.org/UAPROF/ccppschema-20000405#";> + resources/deli/config/vocab/ccppschema-20000405.rdfs + </schemaVocabularyFile> + <schemaVocabularyFile namespace="http://www.wapforum.org/profiles/UAPROF/ccppschema-20010330#";> + resources/deli/config/vocab/ccppschema-20010330.rdfs + </schemaVocabularyFile> + <vocabularyFile> + resources/deli/config/vocab/uaprof_vocab_30apr2001.xml + </vocabularyFile> </deli> ]]></source> <p>This file can contain a number of configuration directives described in @@ -332,10 +349,10 @@ <s3 title="Vocabulary options"> <p>DELI has a number of vocabulary options. Firstly it is possible to configure the vocabulary using an -XML file. Secondly it is possible to -specify the URI to be used for the RDF namespace and the -CC/PP or UAProf namespace. This is important because as -the specifications are revised they adopt new namespaces. +XML file, or if you are using UAProf using a UAProf RDF Schema. +You can find examples of both approaches in this distribution. +Secondly it is possible to +specify the URI to be used for the RDF namespace. Thirdly it is possible to set the string used to represent components and defaults in the vocabulary. This is important because the two standards currently use different cases for @@ -353,9 +370,10 @@ <td>The file containing the vocabulary specification.</td> </tr> <tr> - <td>ccppUri</td> - <td>http://www.wapforum.org/profiles/UAPROF/ccppschema-20010430#</td> - <td>The namespace used for CC/PP constructs such as component.</td> + <td>schemaVocabularyFile</td> + <td>ccppschema-20000405.rdfs</td> + <td>The file containing the vocabulary specification as an UAProf RDF Schema. + Use the attribute <code>namespace</code> to configure which namespace the schema corresponds to.</td> </tr> <tr> <td>rdfUri</td> @@ -377,32 +395,36 @@ </s2> <s2 title="Configuring Legacy Devices"> <p>It is easy to configure DELI to recognise legacy -devices via user-agent strings. The legacy device configuration file maps user-agent -strings on to profile references on a profile repository. -By default this is done in the <code>legacyDevice.xml</code> file, although it is -possible to select a different file. -The legacy device configuration file has the following format:</p> +devices via user-agent strings. A user-agent string is a string sent by the client to +the server as part of the HTTP request. It allows different browsers to be identified. +The legacy device configuration file maps user-agent +strings on to profile either on the local filestore or on a profile repository. +By default this is done in the <code>legacyDevice.xml</code> file which +has the following format:</p> <source><![CDATA[ <?xml version="1.0"?> <devices> <legacyDevice> <useragentstring>MSIE</useragentstring> - <profileref>http://localhost:8080/cocoon/resources/legacyProfiles/msie.rdf</profileref> + <profileref>http://www.profiles.org/legacyProfiles/msie.rdf</profileref> + </legacyDevice> + <legacyDevice> + <useragentstring>mozilla</useragentstring> + <profileref>resources/deli/legacyProfiles/mozSample.rdf</profileref> </legacyDevice> </devices> ]]></source> <p>Where <code>useragentstring</code> is a device unique string found in -the user-agent string of the device and <code>profileref</code> is a URL -for the appropriate profile on a profile repository. </p> +the user-agent string of the device and <code>profileref</code> is either a local file or a URL +for the appropriate legacy profile. </p> </s2> - </s1> <s1 title="Writing CC/PP and UAProf aware stylesheets"> -<p>Once you have got DELI running on Cocoon, the next + <p>Once you have got DELI running on Cocoon, the next step in creating a CC/PP aware site is to create some stylesheets that use profile information. DELI makes CC/PP or UAProf attributes available -to XSLT stylesheets as parameters. As CC/PP attributes are unique -within a profile, the component information is omitted. Hence to retrieve the +to XSLT stylesheets as parameters. In the process of doing this, DELI 'flattens' the profiles +by omitting the component information. Hence to retrieve the <code>CcppAccept</code> attribute you use the XPath <code>deli-capabilities/browser/CcppAccept</code> whereas to retrieve the <code>ScreenSize</code> attribute you use the XPath <code>deli-capabilities/browser/ScreenSize</code>. @@ -411,8 +433,8 @@ Hence to retrieve the individual elements you use the XPath <code>deli-capabilities/browser/CcppAccept/li</code>. The following code demonstrates how to retrieve both a simple and a complex -attribute:</p> - <source><![CDATA[ +attribute. For more complex examples see the <code>deli_test.xsl</code> stylesheet with Cocoon.</p> + <source><![CDATA[ <?xml version="1.0"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"; version="1.0"> <xsl:param name="deli-capabilities"/> @@ -464,5 +486,10 @@ ]]></source> </s1> + <s1 title="More information ?"> + <p>For more information on the DELI library please refer to the +<link href="http://www-uk.hpl.hp.com/people/marbut/";>DELI web-site</link>.</p> + </s1> </body> </document> +
---------------------------------------------------------------------- In case of troubles, e-mail: [EMAIL PROTECTED] To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
