Background information
IBM WebSphere Portlet Factory provides core functionality to call REST
style services using the REST Service Call builder. The REST Service Call
builder assists in invoking the REST style service and generates a default
xsd schema based on introspecting the results of the service call. The
models in this article use the REST Service Call builder to fetch Atom
feed data from a Lotus Connections Dogear, Profiles, and Blogs server.
Also shown is the use of the Atom publishing API to write back to the Blogs
server.
Sample description
Here are some of the techniques illustrated in the sample code:
- These samples illustrate how to
use the REST Service Call Builder to access Atom feed data from Lotus Connection
servers using Service Consumer/Provider architecture. The high level diagram
below shows this architecture.
- How to use View & form and
Data Page builders to display Connections feed data.
- How to update Connections data
using the Atom publishing API.
- How to page through Connections
Atom feed results using the sample Connections Paging builder.
- Use of context Variables to pass
non-input data from the Service Consumer to the Service Provider model
(for example, server connection URLs).
- Filtering Connections data using
tag fields.
Prerequisites
These samples require Portlet Factory 6.0.2. You should have a basic familiarity
with Portlet Factory and be able to create and run Portlet Factory models.
You should understand the Portlet Factory Service Provider/Consumer architecture,
which these sample models make use of. You should also be somewhat familiar
with the
Lotus
Connections Atom API's
and REST style services.
Service Provider Models
The following sections describe the Service Provider models used in the
samples.
Common Context Variables
Each of the Service Provider models use a common set of context variables
that are specified in each Service Operation builder. Context Variables
that are specified in the Consumer are pushed into the corresponding service
model instance variables just before the operation is invoked. These are
used in place of exposing extra inputs to each service operation.
The following is a list of the common variables.
- connectionURL
- Used to push the base URL of the target Connections server to the provider
model.
- userName
- Used to push the current user's name from the consumer model to the provider
model. Used for authentication purposes.
- userPassword
- Used to push the current user's password from the consumer model to the
provider model. Used for authentication purposes.
ProfilesProvider
Model
The ProfilesProvider is a service provider model that performs REST style
calls to retrieve user information from a Lotus Connections Profiles server.
The Profiles data is returned as an Atom feed. The REST Service Call Builder
is used to generate the runtime code to make a request to the server, and
the design time generation of input and results xsd schema information
for each operation in the provider model. The Profile content is returned
within the Atom feed as HTML markup. Because HTML is difficult to operate
on, the provider model uses a Java utility class (ProfileUtils) to convert
the data from HTML to well-formed XML. The conversion of the data is done
by specifying a Post-Execute Method of
"profileUtils.convertProfileData"
in the Additional Processing section of each of the Service Operation builders.
The following are the service operations provided by this model:
profileSearch - Performs a search through the profile data for the
specified user name. The REST call for this request takes the following
parameters, which are passed to the server request:
- name
- The user name to use as the search criteria
- page
- The page number to return for the result data set
- ps
- The number of results to return for a given page
getProfile - Gets the user profile information for the specified user
given their id. The REST call for this request takes the following parameters,
which are passed to the server request:
- uid
- The unique identifier for the user.
- format
- The amount of information to return for the specified "uid".
The builder input has this set to "full".
Note
- See the
Lotus
Connections Atom API
documentation for more information on the meanings of these parameters.
DogearProvider Model
The DogearProvider is a service provider model performs REST style calls
to retrieve user information from a Lotus Connections Dogear server. The
Dogear data is returned as an Atom feed. The REST Service Call builder
is used to generate the runtime code to make a request to the server, and
the design time generation of input and results xsd schema information
for each operation in this provider model.
The following are the service operations provided by this model:
doSearch - Performs a search through all the public Dogear data for
bookmarks that match specified search text. The REST call for this request
takes the following parameters, which are passed to the server request:
- search
- The text to use for the search criteria.
- page
- The page number to return for the result data set.
- ps
- The number of results to return for a given page.
getBookmarks - Gets the Dogear bookmarks for the specified user given
their email address. The REST call for this request takes the following
parameters, which are passed to the server request:
- email
- The email address of the user to get the bookmarks for.
- tag
- This is used to only return bookmarks containing the given tag or tags.
- page
- The page number to return for the result data set.
- ps
- The number of results to return for a given page. Private bookmarks are
returned only when the request is made through an authenticated connection
to the server.
Note - See the
Lotus
Connections Atom API
documentation for more information on the meanings of these parameters.
BlogsProvider Model
The BlogsProvider is a service provider model performs REST style calls
to retrieve Blog entries and comments from a Lotus Connections server.
This model also provides functionality to publish blog data back to the
server. The Blog data is returned as an Atom feed, and the publishing is
done using the Atom publishing API. The REST Service Call builder is used
to generate the runtime code to make requests and publish to the server,
and the design time generation of input and results xsd schema information
for each operation in this provider model.
Context Variables
The following is the context variable specific to this provider model.
See the Common Context Variables section above for information related
to variables that are common to all providers.
blogHandle - All blogs have a blog handle. The handle is specified
when a blog is first created. This handle is used in the construction of
URLs used to query the entries in a given blog.
Operations
The following are the service operations provided by this model:
getBlogEntries - Gets all the entries for the current blog handle.
getBlogTitle - Gets the blog title for the current blog handle.
createBlogEntry - Creates a new blog entry for the current blog handle.
This operation uses the REST service call to perform a POST operation to
create the new entry. The service call for this request takes the following
parameters, which are passed to the server request:
- title
- The title of the new blog entry.
- content
- The HTML markup content for the new blog entry.
updateBlogEntry
- Updates an existing blog entry using its edit URL. This operation uses
the REST service call to perform a PUT operation to update the existing
entry. The service call for this request takes the following parameters,
which are passed to the server request:
- editURL
- The edit URL from the original entry being modified.
- title
- The updated title of the blog entry.
- content
- The updated HTML markup content for the blog entry.
deleteBlogEntry
- Deletes an existing blog entry using its edit URL. This operation uses
the REST service call to perform a DELETE operation to remove the existing
entry. The service call for this request takes the following parameters,
which are passed to the server request:
- editURL
- The edit URL from the original entry being deleted.
getBlogComments
- Gets all the comments for the specified entry of the current blog handle.
The service call for this request takes the following parameters, which
are passed to the server request:
- filterID
- The id of the entry used to filter the comments list. The Blogs server
is currently only capable of returning all comments for all blog entries,
so this filter id is used to remove the ones not associated with the target
entry.
addBlogComment
- Creates a new blog comment for the specified entry of the current blog
handle. This operation uses the REST service call to perform a POST operation
to create the new comment. The service call for this request takes the
following parameters, which are passed to the server request:
- replyToRef
- The reference id of the entry to which the new comment is being added
to.
- content
- The HTML markup content for the new blog comment.
Note
- See the
Lotus
Connections Atom API
documentation for more information on the meanings of these parameters.
Note - The
addEntryData and
updateEntryData methods in
this model are used to decode the blog HTML content that was submitted.
When running in the portal, content is encoded for security reasons.
For more information see
http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp.zos.doc/wps/tbl_sec.html
Service Consumer Models
The following sections describe the Service consumer portlet UI models
used in these samples.
ProfilesPortlet Model
The ProfilesPortlet is a service consumer model displays data from a Lotus
Connections Profiles Atom feed. The ProfilesProvider model described above
is used to interface to the Profiles server and bring the data into the
context of this model. This model provides the UI to perform search, list,
and detail views of user profile data. The following are the high level
pieces of functionality that this model provides.
Search - This allows you to enter a user name or partial name and perform
an initial search for matches. The entered search text is set as the "name"
input of the Data Service (DataServices/profilesData/profileSearch/inputs/profileSearchRestInputs/Parameters/name).
Search results list - This section displays the results from the search
in list. The data is fetched and paged using the Connection Paging builder.
This builder invokes the profileSearch operation from the profilesData
Data Service. The list itself is rendered using a Repeated Region builder
where its data comes from the Variable created by the Connections Paging
builder (Variables/profilesPagingAssistantData).
Details view - This section displays the detailed information for a
selected user's profile. The data for the details is retrieved using the
getProfile operation of the profilesData Data Service. This operation is
fed the id of the selected user. Data Page is used to render the UI for
this page, and is pointed directly at the service results (DataServices/profilesData/getProfile/results/Profile).
The UI is enhanced by using the Rich Data Definition, and Form Layout builders.
Connection Data - The Connection Data is used to set and hold server
connection information for the current user. This is done using a common
model that is imported into this model using the Imported Model builder.
The ConnectionData model contains the initialization code, and connection
information Variables for configuring the portlet.
Profiling
Profiling is used in this model to expose user personalization and administrative
configuration settings in the portal.
connections.profiles.Edit - This profile set is used to control the page
size of the user profile search results in the Connection Paging builder.
connections.connectionInfo.Config - This profile set is used to set the
URL settings that are required to connect to the server. These are exposed
as administrator configuration settings in the portal.
connections.connectionInfo.Edit - This profile set is used to set the user
information required to connect to the server. This includes information
such as whether to use an SSL connection, and the user name and password.
Figure 1. This shows the running Search Profiles Page
Figure 2 This shows the running Search Profile Details Page
DogearPortlet Model
The DogearPortlet is a service consumer model that displays data from a
Lotus Connections Dogear Atom feed. The DogearProvider model described
above is used to interface to the dogear server and to bring the data into
the context of this model. This model provides two views, the first is
the user's personal bookmarks (My Bookmarks), and the second is a search
view (Search) where the user can search through all of the public bookmarks
that match their search criteria.
The user can switch between the two views using a tab style user interface
(UI). The tab functionality is created using the Tab Page builder. The
following are the high level pieces of functionality that this model provides.
My Bookmarks - The My Bookmarks functionality is provided by an external
model that is referenced in this model using a Model Container builder.
By separating this functionality out, you can reuse My Bookmarks in other
models (portlets) without duplication of its contents. The My Bookmarks
functionality is built similar to the search page in this portlet described
below.
Search - This allows you to enter the search criteria to find the related
bookmarks. The entered search text is assigned to the searchText Variable,
This Variable is used as the Override "search" input for the
doSearch operation in the Service Consumer builder. The reason for this
intermediate variable is so that it can be profile enabled, and therefore
exposed as a portlet edit setting (that is, default search text) .
Search results list - This section displays the bookmark results from
the search in list. The data is fetched and paged using the Connection
Paging builder. This builder invokes the doSearch operation from the "dogear"
Data Service. The list itself is rendered using Data Page where its data
comes from the Variable created by the Connections Paging builder (Variables/searchPagingAssistantData).
The links in this list are created using the Link builder using the data
from the Data Page loop variable that contains the current feed bookmark
entry. The target link is in the "href" attribute of the ""
element (Variables/entryLoopVar/entry/link/@href).
Connection Data - The Connection Data is used to set and hold server
connection information for the current user. This is done using a common
model that is imported into this model using the Imported Model builder.
The ConnectionData model contains the initialization code and connection
information Variables for configuring the portlet.
Profiling
Profiling is used in this model to expose user personalization, and administrative
configuration settings in the portal.
connections.dogear.Edit - This profile set is used to control the page
size of the bookmark search results in the Connection Paging builder.
connections.connectionInfo.Config - This profile set is used to set the
URL settings that are required to connect to the server. These are exposed
as administrator configuration settings in the portal.
connections.connectionInfo.Edit - This profile set is used to set the user
information required to connect to the server. This includes information
such as whether to use an SSL connection and the user name and password.
Figure 3. This shows the running Dogear My Bookmarks Page
Figure 4. This shows the running Dogear Search Page
BlogsPortlet Model
The BlogsPortlet is a service consumer model that displays and updates
data from a Lotus Connections Blogs server. The BlogsProvider model described
above is used to interface to the blogs server and bring the data into
the context of this model. The blog entries that are consumed by this model
are based on the specified blog handle. The following are the high level
pieces of functionality that this model provides.
Blog Entries View & Form - This section provides the UI for showing
a list of blog entries. Each entry can be selected to show its details.
This functionality is provided using the View & Form builder.
New Blog Entry - This section adds support for creating a new blog
entry for the current handle. A new blog entry can be added from the main
blog entry list page. The user interface (UI) for this functionality is
provided by using the Input Form builder.
Delete Blog Entry - This section adds support for deleting the current
blog entry. A blog entry can be deleted from the blog entry details page.
The delete is done using the deleteBlogEntry operation and passing it the
editURL for the current blog entry.
View Blog Comments - This section adds a list of comments associated
with the current blog entry to the entry details page. This functionality
is provided using a Data Page builder that uses the results of the getBlogComments
service operation. The service is invoked using an on-load page events
handler.
Add Blog Comments - This section adds support for creating a new comment
associated with the current blog entry. A new blog comment can be added
from the blog entry details page. The UI for this functionality is provided
by using the Input Form builder.
Connection Data - The Connection Data is used to set and hold server
connection information for the current user. This is done using a common
model that is imported into this model using the Imported Model builder.
The ConnectionData model contains the initialization code and connection
information Variables for configuring the portlet.
Profiling
Profiling is used in this model to expose user personalization, and administrative
configuration settings in the portal.
connections.blogs.Edit - This profile set is used to control the blogHandle
user setting.
connections.connectionInfo.Config - This profile set is used to set the
URL settings that are required to connect to the server. These are exposed
as administrator configuration settings in the portal.
connections.connectionInfo.Edit - This profile set is used to set the user
information required to connect to the server. This includes information
such as whether to use an SSL connection, and the user name and password.
Figure 5 This shows the running Blogs View Page
Figure 6 This shows the running Blogs Details Page
Connections Paging Sample Builder
The sample Connections Paging builder provides you with the ability to
navigate through a Connections Atom feed data set. This builder adds an
LJO to the WebApp that wraps the specified data source in an IXml object
and contains methods to access records one "page" at a time.
Use either the built-in Link or Button paging controls or us the Paging
Links or Paging Buttons builder call to manually add the data navigation
controls to the page.
This builder utilizes the opensearch element
that is present in the results from a Connections feed.
The source code for this sample builder is provided in the com.ibm.samples.connections.builders.jar
located in the WEB-INF\work\lib directory of your project.
Notes on running the samples
To run the sample application:
1) Insure you are using WebSphere Portlet Factory 6.0.2 or higher, and
have access to a Lotus Connections 1.0.2 or higher server.
2) Download the connections_samples.zip ZIP file and import it into a project
using the File, Import, WebSphere Portlet Factory Archive command.
3) Open the server information that was added to your project and set the
location of the Lotus Connection servers that you are communicating with.
The file is: WebContent\WEB-INF\samples\connections\server_info.properties
Example:
profiles_url=http://profiles.your.server.com/profiles
dogear_url=http://dogear.your.server.com
default_dogear_email=yourname@yourcompany.com
blogs_url=https://blogs.your.server.com/blogs
blogs_user_name=userName
blogs_user_password=password
| Note
If you are using a secure connection (SSL) to access your server, you must
install a certificate from the target server onto the application server
that is running the model.
If you receive a javax.net.ssl.SSLHandshakeException, you are most likely
missing the proper certificate on your server. |
4) Redeploy the project to your portal or application server.
5) If you are deploying to an application server, you can simply run one
of the sample portlet models samples\connections\DogearPortlet.model, samples\connections\BlogsPortlet.model,
or samples\connections\ProfilesPortlet.model.
6) If you are deploying to a portal, you must add the portlets to a page
in your portal. The sample portlets are named: Profiles Search Portlet
or Dogear Portlet. You must configure each of the portlets to supply the
Connections server URL information.
Use the "Configure" portlet menu option to set the server URL
information. Shown below is a sample configuring the Dogear Portlet, which
is similar for all the portlets. You must be an administrator of the portlet
to access its configuration page.
Download
connections_samples.zip