It seems like a long, long time ago that I first wrote about the sample RESTcommands that we had made available on wlp.bea.com, but in fact it was less than a year. It's amazing how much has happened since then for me, WebLogic Portal, and of course BEA.
A Quick Refresher
My blog entry The REST of the Story includes an introduction to REST, and here are some of the links again if you'd like to read a bit about it:
- RESTful Web Services by Leonard Richardson, Sam Ruby
- Representational State Transfer (REST) - Chapter 5 of Roy T. Fielding's Dissertation
- REST for the Rest of Us, Various
A Web 2.0 Demonstration
You can see the REST commands in WLP 10.2 in action by visiting the Dynamic Visitor Tools Sample site. Follow the link on that page and you'll see this portal desktop:
You can create an account and login very easily, and when you do so it will enable the DVT functionality for things like drag-and-drop, adding portlets/pages/books, and changing the look and feel, layout, menus, and so on. What you might not be aware of is that nearly everything you see is powered by a combination of the WebLogic Portal REST API, the WLP Disc Framework, the Dojo Toolkit, and the Dynamic Visitor Tools Sample code.
Patterns
A visitor to this site will push buttons, make selections, drag and drop items, use inline editing, and so on as part of a Web 2.0 style interactive experience. A common pattern is used for nearly everything in the DVT, illustrated here:
We'll look into Disc more in an upcoming entry, for now we'll start by saying that it makes it easy to get to the client-side representations for portal objects. The DVT sample uses Disc to get information about the portal desktop, including the various labels, titles, DOM nodes, and so on that make them up. Without Disc a portal page is just a collection of DIVs and other HTML tags, and in the past developers often had to invent their own solutions for mapping these to the server-side definitions and instances. Not impossible, but it wasn't always easy and it meant custom solutions that might not interoperate or upgrade well.
Try It!
One thing that makes REST interesting is that it is very easy to use; in fact you can try it out without writing a single line of code. I will suggest that you use Mozilla Firefox with the Firebug add-on as you can do a lot with the console, but any browser will at least let you try the basics. Try the following URL:http://wlp.bea.com/dvt/bea/wlp/api/portlet/list?webapp=dvt
This will return a list of available portlets in the dvt web app, which will look something like this:
The XML is fairly straightforward:
<rsp>
<portlet_summaries> - Array of portlet summarys
<portlet_summary> - Summary for a portlet
<label>portlet_1</label> - The unique label for the portlet
<title>My Portlet</title> - The title to display
<icon>portlets/icons/myportlet.png</icon> - The optional icon
<description>The portlet</description> - The optional description </portlet_summary>
...
</portlet_summaries>
</rsp>
This list can be used to display a list of portlets, as in this example from the DVT Gallery:
A Closer Look
While XML is great for many things, it's not really great on the client side, especially when going cross-browser. It's often easier to use JSON, JavaScript Object Notation, which is fully supported by the WLP REST API. Simply include the argument format=json and you'll get a response that contains JSON, which is easily used on the client. Here is a screenshot from Firebug showing the arguments being used by the DVT to build the gallery listing above:
These include:
- desktop: dvt - The portal desktop, from Disc
- format: json - Return the results as JSON
- max: 200 - Return a maximum of 200 portlet summaries
- portal: demo - The portal, from Disc
- scope: visitor - Can be visitor, admin, or library
- start: 0 - Start with the first portlet
- webapp: The webapp to get the portlets for, from Disc
This will return the following:
This is fairly dense, but if you format it you can see that it is similar to the XML:
{
"content": {
"portlet_summaries": [
{ "title":"My Portlet Customers","label":"portlet_1","icon":"portlets/icons/myportlet.png" },
...
]
}
} If you haven't already used JSON it might not be obvious why this is so much easier than XML. With JSON you can use the JavaScript eval function (or a nice wrapper for it as provided by Dojo and other toolkits) and get a JavaScript object back. This takes just a few lines of code:
var result = eval("(" + XMLHttpRequest.responseText + ")");
var content = result.content;
var portletSummaries = content.portlet_summaries;
for (var i = 0; i < portletSummaries.length; i++) {
var title = portletSummaries[i].title;
var label = portletSummaries[i].label;
... More Examples
You can use the same pattern to get lists of most of the portal resources, using the following pattern:
<protocol>://<host>:<port>/<webapp>/bea/wlp/api/<type>/<action>/<label>?<params>
This is covered in more detail on our edocs site in The WebLogic Portal REST API , which is a good follow-up to this blog entry. If you'd like to explore some more, here are some of the types and actions you can try, all starting with http://wlp.bea.com/dvt/bea/wlp/api/:
- portlet/details/<label>?webapp=dvt - Where label is from the portlet summary
- lookandfeel/list?webapp=dvt
- page/list?webapp=dvt
- book/list?webapp=dvt
- menu/list?webapp=dvt
- theme/list?webapp=dvt
As you've probably noticed, so far the focus has been on reading from the server via HTTP GETs, but there is a lot more you can do using POSTs. The DVT sample uses this to change the look and feel, add portlets to a page, and so on, using the data from the GETs to create the various parameters. You can't really explore POSTs using URLs in the browser, but you can do so with a small amount of code. One thing to note is that you will need to be authenticated in order to do anything interesting, and you can only do the things that the server security allows.
I've got a set of sample portlets that I've been working on that duplicate much of the functionality in the DVT using "plain" JavaScript, with no reliance on Dojo, etc. All you need to do is have Disc enabled in a WebLogic Portal 10.2 desktop. They aren't meant to be examples of how to write portlets so much as they are demonstrations of using REST and Disc, and can be used to learn how to use these technologies with most any framework. I hope to make these available soon, but if you can't wait drop me a line and I'll send you the current set.
More to come on this, and I'll continue with the optimization series as well.
