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 Relative

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>

Move

API: move
Component: AjaxMovePortlet
Description: Move a portlet on a page to a cartesian position (x,y,z,width,height) from request parameters.
Parameters:
page implied in the URL
action move
id the portlet PSML fragment id of the portlet to be moved
x the portlet cartesian X position
y the portlet cartesian Y position
z the portlte cartesian Z position
width the width of the portlet
height the height cartesian Y position
API example: 
			
http://localhost:8080/jetspeed/ajaxapi/Public/public.psml?action=move&id=ps-1003&x=100&y=250&width=200&height=300
XML Response: 
<js>
   <status>success</status>
    <action>move</action>
    <id>ps-1003</id>
	<old_position>
      <x>50</x>
      <y>155</row>
    </old_position>
	<new_position>
      <x>100</x>
      <y>250</y>
    </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>

Permissions

API: permissions
Component: AjaxSecurityPermissions
Description: Security Permissions Maintenance to add, update, and remove permissions from the Jetspeed security policy
Parameters:
action permissions
method the method to execute: must be of value: add | update | remove
type the type of permission being manipulated: portlet | folder | page
resource the name of the portal resource being manipulated
roles comma-separated list of roles, only valid for methods: add, update
actions comma-separated list of actions, only valid for methods: add, update
oldactions comma-separated list of previous actions, only valid for methods: update
API example: 
			
http://localhost:8080/jetspeed/ajaxapi?action=permissions&method=add&type=portlet&resource=demo::*&roles=role1,role2,role3&actions=view,edit
XML Response: 
<js>
    <status>success</status>
    <action>permissions</action>
    <resource>demo::*</resource> 
    <type>portlet</type> 
    <actions>view,edit</actions>
    <actions>role1,role2,role3</actions>    
</js>

getmenus

API: getmenus
Component: AjaxGetMenus
Description: Retrieves all menus for the current page (implied in URL)
Parameters:
action getmenus
page (implied in URL)
API example: 
			
http://localhost:8080/jetspeed/ajaxapi/default-page.psml?action=getmenus
XML Response: 
<js>
    <status>success</status>
    <action>getmenus</action>    
    <menus>
        <menu type="standard">navigations</menu>
        <menu type="standard">back</menu>
        <menu type="standard">pages</menu>
        <menu type="standard">breadcrumbs</menu>
        <menu type="custom">site-navigations</menu>
        <menu type="custom">additional-links</menu>
        <menu type="custom">page-navigations</menu>
    </menus>
</js>

getmenu

API: getmenu
Component: AjaxGetMenu
Description: Retrieves the menu definition for a given menu
Parameters:
action getmenu
menu name of the menu to retrieve (menu definition may change per page)
API example: 
			
http://localhost:8080/jetspeed/ajaxapi?action=getmenu&name=breadcrumbs
XML Response: 
<js>
<status>success</status>
<action>getmenu</action>
<menu>
  <name>breadcrumbs</name>
  <title>You are here:</title>
  <short-title>You are here:</short-title>
  <skin>breadcrumbs</skin>
  <url>/default-page.psml</url>
  <hidden>false</hidden>
  <selected>true</selected>
  <option>
    <type>folder</type>
    <title>Root Folder</title>
    <short-title>Root Folder</short-title>
    <skin>breadcrumbs</skin>
    <url>/</url>
    <hidden>false</hidden>
    <selected>true</selected>
  </option>
  <option>
    <type>page</type>
    <title>Welcome to Jetspeed 2</title>
    <short-title>Welcome to Jetspeed 2</short-title>
    <skin>blue</skin>
    <url>/default-page.psml</url>
    <hidden>false</hidden>
    <selected>true</selected>
  </option>
</menu>
</js>

window

API: getmenus
Component: AjaxChangeWindow
Description: Changes a portlet window's Window State or Portlet Mode
Parameters:
action window
id window id of the portlet to be modified
state A portlet api valid window state or extended window state (normal | maximized | minimized)
mode A portlet api valid portlet mode or extended portlet mode (view | edit | help | print)
page Implied in URL
API example: 
			
http://localhost:8080/jetspeed/ajaxapi?action=window&state=maximized&mode=edit&id=um-2
XML Response: 
<js>
  <status>success</status>
  <action>window</action>
  <id>um-2</id>  
  <state>maximized</state>
  <mode>edit</mode>
</js>

getuseinfo

API: getuseinfo
Component: AjaxGetUserInformation
Description: Returns information about the currently logged in user. Can be used for example in AJAX based portlets to retrieve the userinfo in a more robust way. Will return success only if a user is currenly logged in, otherwise will return false.
Parameters:
action getuserinfo
API example: 
			
http://localhost:8080/jetspeed/ajaxapi?action=getuserinfo
XML Response: 
<js>
    <status>success</status>
    <action>userinformation</action>
    <username>admin</username> 
    <type>org.apache.jetspeed.security.impl.UserPrincipalImpl</type>
    <userinfo>
        <user.name.given>Test Dude</user.name.given>
        <user.name.family>Dudley</user.name.family>
    </userinfo>
</js>

getuserlist

API: getuseinfo
Component: AjaxGetUserList
Description: Provides basic information (username, ip-address, number of sessions and status) about currently logged in users in xml-format. Optionally it can also provide more detailed userinformation, number of guest sessions and include offline users as well.
Parameters:
action getuserinfo
userinfo Whether we should include also userinfo (true | false [default])
offline Whether we should include offline users (true | false [default])
guest Whether we should return also the guest sessions (true | false [default])
all If set to true, will return every bits and piece there is (true | false [default])

By default the private information (emails, etc..) is protected with RolesSecurityBehavior security, but can be changed in AJAX configuration by altering the protectionScope constructor value to either "all" to protect even the basic information or to "none" when everything will be shown for everyone (not wise on production). The default value "private" will show just the basic information of online/offline users and number of guest sessions, as the "private-offline" will not show even the offline users. Possible protectionScope values are "all", "private-offline", "private" and "none".

API example: 
			
http://localhost:8080/jetspeed/ajaxapi?action=getuserlist&userinfo=true&guest=true
XML Response: 
<js>
    <status>success</status>
    <action>getuserlist</action>
    <users>
        <user>
            <username>admin</username>
            <sessions>1</sessions>
            <status>online</status>
            <ipaddress>127.0.0.1</ipaddress>
            <userinfo>
                <user.name.given>Test Dude</user.name.given>
                <user.name.family>Dudley</user.name.family>
            </userinfo>
        </user>
        <guests>0</guests>
    </users>
</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="move">
                <ref bean="AjaxMove"/>
            </entry>            
            <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>
            <entry key="getpages">
                <ref bean="AjaxGetPages"/>
            </entry>			
            <entry key="getfolder">
                <ref bean="AjaxGetFolder"/>
            </entry>			            
            <entry key="getlink">
                <ref bean="AjaxGetLink"/>
            </entry>			                        
            <entry key="getfolderlist">
                <ref bean="AjaxGetFolderList"/>
            </entry>			                        
            <entry key="getfolders">
                <ref bean="AjaxGetFoldersList"/>
            </entry>			      						
            <entry key="getthemes">
                <ref bean="AjaxGetThemes"/>
            </entry>
            <entry key="getactions">
                <ref bean="AjaxGetActions"/>
            </entry>
            <entry key="window">
                <ref bean="AjaxChangeWindow"/>
            </entry>
            <entry key="getmenus">
                <ref bean="AjaxGetMenus"/>
            </entry>			            
            <entry key="getmenu">
                <ref bean="AjaxGetMenu"/>
            </entry>			            
            <entry key="permissions">
                <ref bean="AjaxSecurityPermissions"/>
            </entry>			                        
            <entry key="constraints">
                <ref bean="AjaxSecurityConstraints"/>
            </entry>			          
            <entry key="updatefolder">
                <ref bean="AjaxUpdateFolder"/>                
            </entry>                          
            <entry key="updatepage">
                <ref bean="AjaxUpdatePage"/>                
            </entry>              
            <entry key="updatelink">
                <ref bean="AjaxUpdateLink"/>                
            </entry>                                                              
            <entry key="getuserinfo">
                <ref bean="AjaxGetUserInformation"/>                
            </entry>
            <entry key="getuserlist">
                <ref bean="AjaxGetUserList"/>                
            </entry>
        </map>
    </constructor-arg>
    <constructor-arg index="1">
        <ref bean="AjaxVelocityEngine"/>
    </constructor-arg>
</bean>