AJAX XML API Overview

The Jetspeed XML AJAX API is an XML-based API provided to AJAX clients for making asynchronous requests to Jetspeed-2 services.

Typical use cases:

  • Page Customization and Portlet Placement - To move, copy, add, or remove portlets on a page
  • Layout Selection - change the layout (number of rows and columns, size of columns) on a page
  • Theme and Decorator Selection - change the page theme and portlet decorators on a page.
  • Portlet Selectors - provide a select-list of portlets to the end user
  • Security Configuration - configure the security constraints or policy on a resource (page, portlet, folder, link, fragment), or portal wide
  • Menu Configuration - create and edit menus for the Jetspeed Site
  • General Administration - all use cases for general administration have not yet been explored.

Secured Access

All AJAX XML API requests run through a standard Jetspeed Pipeline request. This means that you can configure your AJAX request with the usual array of Jetspeed components. The default AJAX pipeline secures access to all requests. Each AJAX action may have its own security constraints. All requests made to a page will use the declarative security constraints configured for that page. AJAX request actions are enforced under edit or view mode, depending on the nature of the action.

API

The AJAX XML API is simply a HTTP request-based API, communicating over a simple REST (Representational State Transfer) protocol. The API is accessed over HTTP via the "ajaxapi" servlet path on the portal URL: 

http://hostname/contextname/ajaxapi

Request Parameters and the Page

Request Parameters specify the requested API action, and additional API parameters. The page that a request is referencing is implied in the HTTP URL. Thus if we are making a request to modify a page, the page is specified in the HTTP URL: 

http://localhost:8080/jetspeed/ajaxapi/Public/db-browser.psml
The page location algorithm using standard Jetspeed Profiling rules to locate the page. A page is actually not required in the URL, since the Jetspeed Profiler will locate the page for you. Example: 
http://localhost:8080/jetspeed/ajaxapi
goes to the default page for the current user.

Request Parameters are specific to each API. One request parameter, the "action" parameter, is almost always required, (except in the default case). The default action is "action=getpage" which returns an XML representation of the profile-located page in PSML. (PSML is an XML format). See the table below for specific examples of request parameters.

Here are the APIs currently available:

Get Page

API: getpage
Component: AjaxGetPage
Description: Get Page retrieves a page from the Page Manager store in PSML format.
Parameters:
page implied in the URL
action getportlets (optional, this is the default action)
API example: 
			
http://localhost:8080/jetspeed/ajaxapi/Public/content.psml
XML Response: 
<js>
<status>success</status>
<action>getpage</action>
  <page hidden="false">
  <defaults layout-decorator="tigris" portlet-decorator="tigris"/>
  <name>public.psml</name>
  <path>/Public/public.psml</path>
  <title>Public Share</title>
  <short-title>Public Share</short-title>
  <metadata name="title" xml:lang="es">Carpeta compartida</metadata>
  <fragment id="ps-1000" type="layout" name="jetspeed-layouts::VelocityTwoColumns" decorator="">
    <fragment id="ps-1001" type="portlet" name="rss::RSS" decorator="">
      <property name="row" value="0"/>
      <property name="column" value="0"/>
    </fragment>
	<fragment id="ps-1002" type="portlet" name="demo::BookmarkPortlet" decorator="">
      <property name="row" value="1"/>
      <property name="column" value="1"/>
    </fragment>
	<fragment id="ps-1003" type="portlet" name="jsf-demo::CalendarPortlet" decorator="">
      <property name="row" value="0"/>
      <property name="column" value="1"/>
    </fragment>
	<fragment id="P-1080bff9b03-10000" type="portlet" name="jsf-demo::CalendarPortlet" decorator="">
      <property name="row" value="1"/>
      <property name="column" value="0"/>
    </fragment>
  </fragment>
</page>
</js>

Move Absolute

API: moveabs
Component: AjaxMovePortletAbsolute
Description: Move a portlet on a page to an absolute position specified in the row and col request parameters.
Parameters:
page implied in the URL
action moveabs
id the portlet PSML fragment id of the portlet to be moved
row the absolute new row location to place the portlet fragment (zero based)
col the absolute new column location to place the portlet fragment (zero based)
API example: 
			
http://localhost:8080/jetspeed/ajaxapi/Public/public.psml?action=moveabs&id=ps-1003&row=0&col=1
XML Response: 
<js>
   <status>success</status>
    <action>moveabs</action>
    <id>ps-1003</id>
	<old_position>
      <col>1</col>
      <row>1</row>
    </old_position>
	<new_position>
      <col>1</col>
      <row>0</row>
    </new_position>
</js>

Move

APIs: moveleft, moveright, moveup, movedown
Components: AjaxMovePortletLeft, AjaxMovePortletRight, AjaxMovePortletUp, AjaxMoveDown
Description: Move a portlet on a page relatively one position, based on the action.
Parameters:
page implied in the URL
action moveleft, moveright, moveup, movedown
id the portlet PSML fragment id of the portlet to be moved
API example: 
			
http://localhost:8080/jetspeed/ajaxapi/Public/public.psml?action=movedown&id=ps-1003
XML Response: 
<js>
   <status>success</status>
    <action>movedown</action>
    <id>ps-1003</id>
	<old_position>
      <col>1</col>
      <row>0</row>
    </old_position>
	<new_position>
      <col>1</col>
      <row>1</row>
    </new_position>
</js>

Add Portlet

API: add
Component: AjaxAddPortlet
Description: Adds a new portlet to the current page. The portlet can be added at a specified row and column. If either the row or column or not specified, defaults to zero respectively.
Parameters:
page implied in the URL
action add
id The portlet full name to be placed on the page, using Jetspeed Portlet Naming (PortletApplicationName::PortletName)
row optional: the absolute new row location to place the new portlet fragment (zero based)
col optional: the absolute new column location to place the new portlet fragment (zero based)
API example: 
			
http://localhost:8080/jetspeed/ajaxapi/Public/public.psml?action=add&id=jsf-demo::CalendarPortlet
XML Response: 
<js>
  <status>success</status>
  <action>add</action>
  <id>jsf-demo::CalendarPortlet</id>
  <new_position>
    <col>0</col>
    <row>0</row>
  </new_position>
</js>

Remove Portlet

API: remove
Component: AjaxRemovePortlet
Description: Removes a new portlet from the current page.
Parameters:
page implied in the URL
action remove
id the portlet PSML fragment id of the portlet to be removed
API example: 
			
http://localhost:8080/jetspeed/ajaxapi/Public/public.psml?action=remove&id=ps-1003
XML Response: 
<js>
  <status>success</status>
  <action>remove</action>
  <id>jsf-demo::CalendarPortlet</id>
  <new_position>
    <col>0</col>
    <row>0</row>
  </new_position>
</js>

Get Portlets

API: getportlets
Component: AjaxGetPortlets
Description: Get Portlets retrieves the (sorted) portlet list available to the current subject, filtered the portlet list, and returning portlets which the current subject may view. The Jetspeed (JAAS) security policy enforces this filtering. Portlets are returned in XML format, with name, displayName, and description for each portlet.
Parameters:
page implied in the URL
action getportlets
filter not yet implemented. A query filter to be defined.
API example: 
			
http://localhost:8080/jetspeed/ajaxapi?action=getportlets
XML Response: 
<js>
<status>success</status>
<action>getportlets</action>
-
	<portlets>
<portlet name="demo::AttributeScopePortlet" displayName="Attribute Scope Demo" description="$portlet.Description">
        </portlet>
<portlet name="demo::BookmarkPortlet" displayName="Bookmark Portlet" description="Bookmark Portlet">
        </portlet>
<portlet name="demo::BookmarkPortletForXHTMLBasic" displayName="Bookmark Portlet for XHTML Basic" description="Bookmark Portlet for XHTML Basic">
        </portlet>
<portlet name="demo::CSSDemoPortlet" displayName="CSS Demo Portlet" description="$portlet.Description">
        </portlet>
....
<portlet name="rss::RSS" displayName="RSS Portlet" description="RSS Portlet">
        </portlet>
<portlet name="rss::RomeRSS" displayName="Rome RSS Portlet" description="Rome RSS Portlet">
        </portlet>
</portlets>
</js>

Spring Assembly

The AjaxRequestService is a Spring component that handles AJAX requests. It is hooked into the AJAX Pipeline for special processing of AJAX request. Here is the Spring Assembly. Each API is configured in the Ajax Service. 

	
<bean id="AjaxRequestService" class="org.apache.jetspeed.ajax.AjaxRequestServiceImpl">
    <constructor-arg index="0">
        <map>
            <entry key="moveabs">
                <ref bean="AjaxMovePortletAbsolute"/>
            </entry>
            <entry key="moveleft">
                <ref bean="AjaxMovePortletLeft"/>
            </entry>
            <entry key="moveright">
                <ref bean="AjaxMovePortletRight"/>
            </entry>
            <entry key="moveup">
                <ref bean="AjaxMovePortletUp"/>
            </entry>
            <entry key="movedown">
                <ref bean="AjaxMovePortletDown"/>
            </entry>
            <entry key="add">
                <ref bean="AjaxAddPortlet"/>
            </entry>
            <entry key="remove">
                <ref bean="AjaxRemovePortlet"/>
            </entry>
            <entry key="getportlets">
                <ref bean="AjaxGetPortlets"/>
            </entry>
            <entry key="getpage">
                <ref bean="AjaxGetPage"/>
            </entry>
        </map>
    </constructor-arg>
    <constructor-arg index="1">
        <ref bean="AjaxVelocityEngine"/>
    </constructor-arg>
</bean>