[Osr-101] rev 20287 - public/osr-101/trunk
michi at wyona.com
michi at wyona.com
Fri Nov 24 00:46:54 CET 2006
Author: michi
Date: 2006-11-24 00:46:53 +0100 (Fri, 24 Nov 2006)
New Revision: 20287
Modified:
public/osr-101/trunk/draft-neutron-protocol-v0.xml
Log:
exceptions and authentication added*
Modified: public/osr-101/trunk/draft-neutron-protocol-v0.xml
===================================================================
--- public/osr-101/trunk/draft-neutron-protocol-v0.xml 2006-11-23 23:40:08 UTC (rev 20286)
+++ public/osr-101/trunk/draft-neutron-protocol-v0.xml 2006-11-23 23:46:53 UTC (rev 20287)
@@ -90,7 +90,7 @@
</address>
</author>
- <date day="17" month="November" year="2006"/>
+ <date day="23" month="November" year="2006"/>
<abstract>
<t>The Neutron Protocol is an XML-based application-level protocol for remote content authoring. Neutron provides a generic API to what common Content Management Systems (CMS) support with respect to content authoring.</t>
@@ -133,11 +133,14 @@
<section title="Example">
<figure>
<artwork>
- <html>
- <head>
- <link rel="neutron-introspection" type="application/neutron+xml" href="introspection-hello-world.xml"/>
- <title>Hello World</title>
- ...
+<html>
+ <head>
+ <link rel="neutron-introspection" type="application/neutron+xml" href="introspection-hello-world.xml"/>
+ <title>Hello World</title>
+ ...
+ </head>
+ ...
+</html>
</artwork>
</figure>
</section>
@@ -148,12 +151,14 @@
<section title="Introspection Example">
<figure>
<artwork>
- <introspection>
- <edit mime-type="application/xhtml+xml" name="Homepage">
- <open url="index.xhtml" method="GET"/>
- <save url="index.xhtml?yanel.resource.usecase=save" method="POST"/>
- </edit>
- </introspection>
+<?xml version="1.0"?>
+
+<introspection>
+ <edit mime-type="application/xhtml+xml" name="Homepage">
+ <open url="index.xhtml" method="GET"/>
+ <save url="index.xhtml?yanel.resource.usecase=save" method="POST"/>
+ </edit>
+</introspection>
</artwork>
</figure>
</section>
@@ -176,12 +181,14 @@
<section title="Introspection Example">
<figure>
<artwork>
- <introspection>
- <edit mime-type="application/xhtml+xml" name="Homepage">
- <checkout url="index.xhtml?yanel.resource.usecase=checkout" method="GET"/>
- <checkin url="index.xhtml?yanel.resource.usecase=checkin" method="PUT"/>
- </edit>
- </introspection>
+<?xml version="1.0"?>
+
+<introspection>
+ <edit mime-type="application/xhtml+xml" name="Homepage">
+ <checkout url="index.xhtml?yanel.resource.usecase=checkout" method="GET"/>
+ <checkin url="index.xhtml?yanel.resource.usecase=checkin" method="PUT"/>
+ </edit>
+</introspection>
</artwork>
</figure>
</section>
@@ -211,11 +218,13 @@
<section title="Introspection Example">
<figure>
<artwork>
- <introspection xmlns="http://www.wyona.org/neutron/1.0">
- <navigation>
- <sitetree href="sitetree.xml" method="GET"/>
- </navigation>
- </introspection>
+<?xml version="1.0"?>
+
+<introspection xmlns="http://www.wyona.org/neutron/1.0">
+ <navigation>
+ <sitetree href="sitetree.xml" method="GET"/>
+ </navigation>
+</introspection>
</artwork>
</figure>
</section>
@@ -229,6 +238,111 @@
<t>TBD</t>
</section>
+ <section title="Exceptions">
+ <t>If a Neutron-capable client issues a request, the server can respond with exceptions. The following exceptions are defined by the Neutron protocol.</t>
+ <t>Neutron exceptions have a root element "<exception>" with a "type" attribute, specifying the kind of exception. This element then contains a "<message>" element which can contain a human-readable representation of the exception.</t>
+ <t>The second element is defined by the exception type (for details, see the various exception types below).</t>
+ <section title="Authentication">
+ <t>Note that this section is basically the specification of Neutron-Auth, a separate protocol which allows the authentication of clients using arbitrary inputs.</t>
+ <t>Server response upon a client request which requires authentication:</t>
+ <figure>
+ <artwork>
+<?xml version="1.0"?>
+
+<exception xmlns="http://www.wyona.org/neutron/1.0" type="authorization">
+ <message>Authorization denied for "URL" ...</message>
+
+ <authentication>
+ <login url="https://demo.phoenix.wyona.org/protected/?action=login-neutron">
+ <message>Login for realm 'phoenix-demo' ...</message>
+ <form>
+ <param description="Username" name="username"/>
+ <param description="Password" name="passwd"/>
+ </form>
+ </login>
+ <logout url="http://demo.phoenix.wyona.org/?action=logout"/>
+ </authentication>
+</exception>
+ </artwork>
+ </figure>
+ <t>New client request:</t>
+ <figure>
+ <artwork>
+<?xml version="1.0"?>
+
+<authentication xmlns="http://www.wyona.org/neutron/1.0">
+ <param name="username">lenya</param>
+ <param name="passwd">levi</param>
+</authentication>
+ </artwork>
+ </figure>
+ </section>
+
+ <section title="Checkout">
+ <figure>
+ <artwork>
+<?xml version="1.0"?>
+
+<exception xmlns="http://www.wyona.org/neutron/1.0" type="checkout">
+ <message>Document has already been checked-out by ...</message>
+
+ <checkout url="/hello/world.html">
+ <locked-by>Jimi Hendrix</locked-by>
+ <lock-date format="standard">1969.10.03T15:34:26</lock-date>
+ <!-- Optional. Depending on server implementation -->
+ <break-lock url="/hello/world.html?yanel.resource.usecase=break-lock"/>
+ </checkout>
+</exception>
+ </artwork>
+ </figure>
+ <t>How does the server respond to the "break-lock" request?</t>
+ <t>
+ <list style="symbols">
+ <t>Server breaks lock, check-out for new user and returns content.</t>
+ <t>Server breaks lock and returns lock broken successfully, please retry opening again ...</t>
+ <t>Server responds breaking the lock failed for whatever reason.</t>
+ </list>
+ </t>
+ </section>
+
+ <section title="Checkin">
+ <t>If the server cannot save the data, then it should return HTTP Status Code 500 and a message.</t>
+ <figure>
+ <artwork>
+<?xml version="1.0"?>
+
+<exception xmlns="http://www.wyona.org/neutron/1.0" type="checkin">
+ <message>Checkin failed, because document has been checked-out by ...</message>
+
+ <checkin url="/hello/world.html">
+ <locked-by>Jimi Hendrix</locked-by>
+ <lock-date format="standard">1969.10.03T15:34:26</lock-date>
+ <!-- Optional. Depending on server implementation -->
+ <break-lock url="/hello/world.html?yanel.resource.usecase=break-lock"/>
+ </checkin>
+</exception>
+ </artwork>
+ </figure>
+ </section>
+
+ <section title="Data Not Well-Formed">
+ <t>If the server cannot save the data, then it should return HTTP Status Code 500 and a message.</t>
+ <figure>
+ <artwork>
+<?xml version="1.0"?>
+
+<exception xmlns="http://www.wyona.org/neutron/1.0" type="data-not-well-formed">
+ <message>Received data is not well-formed XML ...</message>
+
+ <data-not-well-formed url="/hello/world.html">
+ <line number="45" message="element not closed"/>
+ </data-not-well-formed>
+</exception>
+ </artwork>
+ </figure>
+ </section>
+ </section>
+
<section title="Notational Conventions">
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in <xref target="RFC2119"/>.</t>
More information about the Osr-101
mailing list