Jetspeed 2 Enterprise Portal

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>

Essentials

Building

Get Jetspeed-2.1.3

Documentation

About Jetspeed-2

Support

Translation

Project Documentation

AJAX XML API Overview

Secured Access

API

Request Parameters and the Page

Get Page

Move Absolute

Move Relative

Move

Add Portlet

Remove Portlet

Get Portlets

Permissions

getmenus

getmenu

window

getuseinfo

getuserlist

Spring Assembly