Author: woonsan
Date: Fri Dec 18 20:06:02 2009
New Revision: 892363
URL: http://svn.apache.org/viewvc?rev=892363&view=rev
Log:
JS2-1087: Adding initial documentation for Jetspeed REST API.
To-dos: complete all apis
Added:
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-dev/src/site/xdoc/guide-rest-api.xml
(with props)
Modified:
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-dev/src/site/site.xml
Modified:
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-dev/src/site/site.xml
URL:
http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-dev/src/site/site.xml?rev=892363&r1=892362&r2=892363&view=diff
==============================================================================
--- portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-dev/src/site/site.xml
(original)
+++ portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-dev/src/site/site.xml Fri
Dec 18 20:06:02 2009
@@ -95,6 +95,7 @@
<menu name="APIs" >
<item name="Jetspeed Java API"
href="../apidocs/jetspeed-api/index.html" />
<item name="Jetspeed AJAX API" href="guide-ajax-api.html" />
+ <item name="Jetspeed REST API" href="guide-rest-api.html" />
<item name="Full Javadocs" href="../apidocs/index.html" />
</menu>
Added:
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-dev/src/site/xdoc/guide-rest-api.xml
URL:
http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-dev/src/site/xdoc/guide-rest-api.xml?rev=892363&view=auto
==============================================================================
---
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-dev/src/site/xdoc/guide-rest-api.xml
(added)
+++
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-dev/src/site/xdoc/guide-rest-api.xml
Fri Dec 18 20:06:02 2009
@@ -0,0 +1,321 @@
+<?xml version="1.0"?>
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<document>
+ <properties>
+ <title>REST API</title>
+ <subtitle>Documentation for Jetspeed REST API</subtitle>
+ <authors>
+ <person name="Woonsan Ko" email="[email protected]"/>
+ </authors>
+ </properties>
+ <body>
+<section name="Jetspeed REST API Overview">
+<p>
+The Jetspeed REST API is an RESTful web services for clients (including AJAX
clients) for making HTTP requests to Jetspeed services.
+</p>
+<p>
+The URLs for the Jetspeed REST API starts with the following:
+<source><![CDATA[
+http://hostname/contextname/services/
+]]></source>
+</p>
+<p>
+Typical use cases:
+</p>
+<ul>
+ <li><b>Page Customization and Portlet Placement</b> - To move, copy, add,
or remove portlets on a page</li>
+ <li><b>Layout Selection</b> - change the layout (number of rows and
columns, size of columns) on a page</li>
+ <li><b>Theme and Decorator Selection</b> - change the page theme and
portlet decorators on a page.</li>
+ <li><b>Portlet Selectors</b> - provide a select-list of portlets to the
end user</li>
+ <li><b>Security Configuration</b> - configure the security constraints or
policy on a resource (page, portlet, folder, link, fragment), or portal
wide</li>
+ <li><b>Menu Configuration</b> - create and edit menus for the Jetspeed
Site</li>
+ <li><b>General Administration</b> - all use cases for general
administration have not yet been explored.</li>
+</ul>
+<subsection name='Secured Access'>
+<p>
+All Jetspeed REST API requests run through
+a standard Jetspeed <a href='guide-pipeline.html'>Pipeline</a> request. This
means that you can configure your web
+request with the usual array of Jetspeed components. The default REST services
pipeline secures
+access to all requests. Each service may have its own security constraints. All
+requests made to a page will use the declarative security constraints
configured for that page.
+REST request actions are enforced under edit or view mode, depending on the
nature of the action.
+</p>
+</subsection>
+<subsection name='Flexible Message Media Types for Message Producers and
Consumers'>
+<p>
+All Jetspeed REST API support dual Message Media Types for Message producers
and consumers: 'application/json' and 'application/xml'
+with help of the underlying <a href="http://cxf.apache.org";>Apache CXF</a>
JAX-RS Server.
+Typically, web client applications can use JSON marshaling/unmarshaling by
adding '_type=json' parameter in the request URLs.
+If the parameter is '_type=xml', then the messages are XML messages.
+If the '_type' parameter is not set by the client, the Jetspeed REST API read
the 'Accept' HTTP request header to decide
+which is proper for the web client. Please see the documents of Apache CXF for
details.
+</p>
+</subsection>
+<subsection name='XML Schema Support'>
+<p>
+You can also retrieve XML Schema document for each service simply by adding
'?_wadl' query string.
+Apache CXF JAX-RS server, on which Jetspeed REST API depends, generates the
XML Schema document for the service automatically.
+For example, you can request the following URL to retrieve the XML Schema
document for 'Get Portlet Application' service of 'Portlet Registry Service'.
+<source><![CDATA[
+http://localhost:8080/jetspeed/services/portletregistry/application/demo/?_wadl
+]]></source>
+</p>
+</subsection>
+</section>
+<section name='Portlet Registry Service'>
+<p>
+The Portlet Registry Service is a HTTP request-based API, communicating over a
simple REST (Representational State Transfer) protocol,
+providing information and management functionality on portlet applications and
portlet definitions.
+This service is accessed over HTTP via the "/services/portletregistry" path on
the portal URL:
+<source><![CDATA[
+http://hostname/contextname/services/portletregistry/
+]]></source>
+</p>
+
+<subsection name='Get Portlet Applications'>
+<table>
+ <tr>
+ <td>Entry path</td>
+ <td>/application/</td>
+ </tr>
+ <tr>
+ <td>Description:</td>
+ <td>Get portlet applications based on the path parameter for
application name.</td>
+ </tr>
+ <tr>
+ <td>Parameters</td>
+ <td>
+ <table>
+ <tr>
+ <th>Type</th>
+ <th>Name</th>
+ <th>Example value</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>PATH</td>
+ <td>name</td>
+ <td>/demo/</td>
+ <td>
+ Portlet application name.
+ If the portlet application name path parameter is not
provided, then
+ all portlet applications are retrieved.
+ </td>
+ </tr>
+ <tr>
+ <td>QUERY</td>
+ <td>query</td>
+ <td>tool</td>
+ <td>Search query string to filter the results.</td>
+ </tr>
+ <tr>
+ <td>QUERY</td>
+ <td>begin</td>
+ <td>0</td>
+ <td>The begin index of the page to be selected from the
result.</td>
+ </tr>
+ <tr>
+ <td>QUERY</td>
+ <td>max</td>
+ <td>10</td>
+ <td>The maximum page size to be selected from the
result.</td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+ <tr>
+ <td>REST API examples:</td>
+ <td>
+<source><![CDATA[
+http://localhost:8080/jetspeed/services/portletregistry/application/demo/?_type=json
+
+http://localhost:8080/jetspeed/services/portletregistry/application/?_type=json&query=demo&begin=0&max=10
+]]></source>
+ </td>
+ </tr>
+ <tr>
+ <td>JSON Response Example:</td>
+ <td>
+<source><![CDATA[
+{
+ "beginIndex":-1,
+ "totalSize":1,
+ "applications":[
+ {
+ "name":"demo",
+ "contextPath":"/demo",
+ "applicationType":0,
+ "defaultNamespace":"",
+ "revision":2,
+ "checksum":2832348922,
+ "displayNames":[
+ {
+ "value":"Demoportlets",
+ "lang":"en",
+ "localeString":"en"
+ }
+ ],
+ "descriptions":[
+ {
+ "value":"Demo Portlets Applications",
+ "lang":"en",
+ "localeString":"en"
+ }
+ ],
+ "metadata":
+ {
+ "fields":[
+ {
+ "name":"title",
+ "value":"Title 1",
+ "localeString":"en"
+ },
+ {
+ "name":"title",
+ "value":"Eng Title",
+ "localeString":"en"
+ }
+ ]
+ },
+ "containerRuntimeOptions":[]
+ }
+ ]
+}
+]]></source>
+
+ </td>
+ </tr>
+ <tr>
+ <td>XML Response Example:</td>
+ <td>
+<source><![CDATA[
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<data>
+ <beginIndex>-1</beginIndex>
+ <totalSize>1</totalSize>
+ <applications>
+ <application>
+ <applicationType>0</applicationType>
+ <checksum>2832348922</checksum>
+ <containerRuntimeOptions/>
+ <contextPath>/demo</contextPath>
+ <defaultNamespace/>
+ <descriptions>
+ <description>
+ <lang>en</lang>
+ <localeString>en</localeString>
+ <value>Demo Portlets Applications</value>
+ </description>
+ </descriptions>
+ <displayNames>
+ <displayName>
+ <lang>en</lang>
+ <localeString>en</localeString>
+ <value>Demoportlets</value>
+ </displayName>
+ </displayNames>
+ <metadata>
+ <fields>
+ <field>
+ <localeString>en</localeString>
+ <name>title</name>
+ <value>Title 1</value>
+ </field>
+ <field>
+ <localeString>en</localeString>
+ <name>title</name>
+ <value>Eng Title</value>
+ </field>
+ </fields>
+ </metadata>
+ <name>demo</name>
+ <revision>2</revision>
+ </application>
+ </applications>
+</data>
+]]></source>
+
+ </td>
+ </tr>
+</table>
+</subsection>
+
+
+
+</section>
+
+<section name='Spring Assembly'>
+<p>
+The Jetspeed REST Services are configured in the Spring Assembly.
+Here is the core part of the Spring Assembly. Each service component is
configured in the Ajax Service.
+</p>
+<source><![CDATA[
+ <!--
+ The internal server factory.
+ Each JAX-RS service component is registered by "resourceProvider" property.
+ -->
+
+ <bean id="cxfJaxrsServerFactoryBean"
class="org.apache.cxf.jaxrs.JAXRSServerFactoryBean">
+ <meta key="j2:cat" value="default" />
+ <property name="address" value="/" />
+ <property name="destinationFactory" ref="cxfDestinationFactory" />
+ <property name="providers">
+ <list>
+ <ref bean="jaxrsJsonProvider" />
+ </list>
+ </property>
+ <property name="resourceProviders">
+ <list>
+
+ <!-- PortletRegistryService component reference -->
+ <bean class="org.apache.cxf.jaxrs.lifecycle.SingletonResourceProvider">
+ <meta key="j2:cat" value="default" />
+ <constructor-arg ref="jaxrsPortletRegistryService" />
+ </bean>
+
+ <!-- PageLayoutService component reference -->
+ <bean class="org.apache.cxf.jaxrs.lifecycle.SingletonResourceProvider">
+ <meta key="j2:cat" value="default" />
+ <constructor-arg ref="jaxrsPageLayoutService" />
+ </bean>
+
+ </list>
+ </property>
+ </bean>
+
+ <!-- Portlet Registry JAX-RS Service -->
+ <bean id="jaxrsPortletRegistryService"
class="org.apache.jetspeed.services.rest.PortletRegistryService">
+ <meta key="j2:cat" value="default" />
+ <constructor-arg
ref="org.apache.jetspeed.security.SecurityAccessController" />
+ <constructor-arg
ref="org.apache.jetspeed.components.portletregistry.PortletRegistry" />
+ <constructor-arg ref="org.apache.jetspeed.search.SearchEngine" />
+ </bean>
+
+ <!-- Portal Page Management JAX-RS Service -->
+ <bean id="jaxrsPageLayoutService"
class="org.apache.jetspeed.services.rest.PageLayoutService">
+ <meta key="j2:cat" value="default" />
+ <constructor-arg ref="org.apache.jetspeed.layout.PageLayoutComponent" />
+ <constructor-arg
ref="org.apache.jetspeed.components.portletregistry.PortletRegistry" />
+ <constructor-arg ref="PortletActionSecurityBehavior" />
+ </bean>
+]]></source>
+
+</section>
+</body>
+</document>
+
Propchange:
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-dev/src/site/xdoc/guide-rest-api.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange:
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-dev/src/site/xdoc/guide-rest-api.xml
------------------------------------------------------------------------------
svn:keywords = Id
Propchange:
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-dev/src/site/xdoc/guide-rest-api.xml
------------------------------------------------------------------------------
svn:mime-type = text/plain
