[exo-jcr-commits] exo-jcr SVN: r2889 - in jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules: ws and 1 other directory.
do-not-reply at jboss.org
do-not-reply at jboss.org
Thu Aug 5 10:54:34 EDT 2010
Author: dkatayev
Date: 2010-08-05 10:54:33 -0400 (Thu, 05 Aug 2010)
New Revision: 2889
Removed:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/introduction-to-rest.xml
Modified:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws.xml
Log:
EXOJCR-870 WS documentation cleaned up
Deleted: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/introduction-to-rest.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/introduction-to-rest.xml 2010-08-05 14:50:43 UTC (rev 2888)
+++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/introduction-to-rest.xml 2010-08-05 14:54:33 UTC (rev 2889)
@@ -1,212 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id = "WS.Introduction">
- <?dbhtml filename="ch-introduction-to-rest.html"?>
-
- <title>Introduction to the Representational State Transfer (REST)</title>
-
- <section>
- <title>Introduction</title>
-
- <para><command>Representational State Transfer (REST)</command> is a style
- of software architecture for distributed hypermedia systems such as the
- World Wide Web. The term was introduced in the doctoral dissertation in
- 2000 by Roy Fielding, one of the principal authors of the Hypertext
- Transfer Protocol (HTTP) specification, and has come into widespread use
- in the networking community.</para>
-
- <para>REST strictly refers to a collection of network architecture
- principles that outline how resources are defined and addressed. The term
- is often used in a looser sense to describe any simple interface that
- transmits domain-specific data over HTTP without an additional messaging
- layer such as SOAP or session tracking via HTTP cookies.</para>
-
- <para>The key abstraction of information in REST is a
- <command>resource</command>. Any information that can be named can be a
- resource: a document or image, a temporal service (e.g. "today's weather
- in Los Angeles"), a collection of other resources, a non-virtual object
- (e.g. a person), and so on. In other words, any concept that might be the
- target of an author's hypertext reference must fit within the definition
- of a resource. A resource is a conceptual mapping to a set of entities,
- not the entity that corresponds to the mapping at any particular point in
- time.</para>
-
- <para>REST uses a <command>resource identifier </command>to identify the
- particular resource involved in an interaction between components. REST
- connectors provide a generic interface for accessing and manipulating the
- value set of a resource, regardless of how the membership function is
- defined or the type of software that is handling the request. URL or URN
- are the examples of a resource identifier.</para>
-
- <para>REST components perform actions with a resource by using a
- <command>representation</command> to capture the current or intended state
- of that resource and transferring that representation between components.
- A representation is a sequence of bytes, plus <command>representation
- metadata </command>to describe those bytes. Other commonly used but less
- precise names for a representation include: <command>document, file, and
- HTTP message entity, instance, or variant</command>. A representation
- consists of data, metadata describing the data, and, on occasion, metadata
- to describe the metadata (usually for the purpose of verifying message
- integrity). Metadata are in the form of name-value pairs, where the name
- corresponds to a standard that defines the value's structure and
- semantics. The data format of a representation is known as a media
- type.</para>
-
- <table>
- <title>REST Data Elements</title>
-
- <tgroup cols="2">
- <thead>
- <row>
- <entry align="center">Data Element</entry>
-
- <entry align="center">Modern Web Examples</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>resource</entry>
-
- <entry>the intended conceptual target of a hypertext
- reference</entry>
- </row>
-
- <row>
- <entry>resource identifier</entry>
-
- <entry>URL, URN</entry>
- </row>
-
- <row>
- <entry>representation</entry>
-
- <entry>HTML document, JPEG image</entry>
- </row>
-
- <row>
- <entry>representation metadata</entry>
-
- <entry>media type, last-modified time</entry>
- </row>
-
- <row>
- <entry>resource metadata</entry>
-
- <entry>source link, alternates, vary</entry>
- </row>
-
- <row>
- <entry>control data</entry>
-
- <entry>if-modified-since, cache-control</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>REST uses various <command>connector</command> types to encapsulate
- the activities of accessing resources and transferring resource
- representations. The connectors present an abstract interface for
- component communication, enhancing simplicity by providing a complete
- separation of concepts and hiding the underlying implementation of
- resources and communication mechanisms.</para>
-
- <table>
- <title>REST Connectors</title>
-
- <tgroup cols="2">
- <thead>
- <row>
- <entry align="center">Connector</entry>
-
- <entry align="center">Modern Web Examples</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>client</entry>
-
- <entry>libwww, libwww-perl</entry>
- </row>
-
- <row>
- <entry>server</entry>
-
- <entry>libwww, Apache API, NSAPI</entry>
- </row>
-
- <row>
- <entry>cache</entry>
-
- <entry>browser cache, Akamai cache network</entry>
- </row>
-
- <row>
- <entry>resolver</entry>
-
- <entry>bind (DNS lookup library)</entry>
- </row>
-
- <row>
- <entry>tunnel</entry>
-
- <entry><para></para>SOCKS, SSL after HTTP CONNECT</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>The primary connector types are client and server. The essential
- difference between the two is that a client initiates communication by
- making a request, whereas a server listens for connections and responds to
- requests in order to supply access to its services. A component may
- include both client and server connectors.</para>
-
- <para>An important part of RESTful architecture is a well-defined
- interface to communicate, in particular it is a set of HTTP methods such
- as POST, GET, PUT and DELETE. These methods are often compared with the
- CREATE, READ, UPDATE, DELETE (CRUD) operations associated with database
- technologies. An analogy can also be made:</para>
-
- <itemizedlist>
- <listitem>
- <para>PUT is analogous to CREATE or PASTE OVER,</para>
- </listitem>
-
- <listitem>
- <para>GET to READ or COPY,</para>
- </listitem>
-
- <listitem>
- <para>POST to UPDATE or PASTE AFTER, and</para>
- </listitem>
-
- <listitem>
- <para>DELETE to DELETE or CUT.</para>
- </listitem>
- </itemizedlist>
-
- <para><command>Note</command>: RESTful architecture is not limited to
- those methods, one of good examples of extension is the WebDAV
- protocol.</para>
-
- <para>The <command>CRUD</command> (Create, Read, Update and Delete) verbs
- are designed to operate with atomic data within the context of a database
- transaction. REST is designed around the atomic transfer of a more complex
- state and can be viewed as a mechanism for transferring structured
- information from one application to another.</para>
-
- <para>HTTP separates the notions of a web server and a web browser. This
- allows the implementation of each to vary from the other based on the
- client/server principle. When used RESTfully, HTTP is
- <command>stateless</command>. Each message contains all the information
- necessary to understand the request.</para>
-
- <para>As a result, neither the client nor the server needs to remember any
- communication-state between messages. Any state retained by the server
- must be modeled as a resource..</para>
- </section>
-</chapter>
Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws.xml 2010-08-05 14:50:43 UTC (rev 2888)
+++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws.xml 2010-08-05 14:54:33 UTC (rev 2889)
@@ -9,15 +9,12 @@
<xi:include href="ws/ws.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="ws/introduction-to-rest.xml"
- xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="ws/rest-framework.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="ws/groovy-scripts-as-rest-services.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="ws/rest-framework.xml"
- xmlns:xi="http://www.w3.org/2001/XInclude" />
-
<xi:include href="ws/framework-for-cross-domain-ajax.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
More information about the exo-jcr-commits
mailing list