Skip to end of metadata
Go to start of metadata

Introduction

The management component of the portal allows portal resources to be managed over commons interfaces like REST, CLI, and Portlets/Gadgets. This guide will discuss these interfaces as well as general portal management concepts and terms. It will then discuss specific management extensions included in the portal.

Terms

Term Description
Management Extension An extension to the management system which defines a managed component.
Managed Component                        
A managed component, which has been registered via an extension, serves as the root managed resource for a component.
Managed Resource
A managed resource is a uniquely identified self describing 'resource' which can have operations and sub-resources registered to it.
Sub-resource
A managed resource whose parent is also a managed resource.
Address
A management address is just the path of the managed resource with syntax similar to a file on a file system, ie: /foo/bar
Operation
An action that can be performed on a managed resource.
Attributes
Custom input parameters available to operations.

Goals

The management component provides a foundation for managing portal side components. By doing so it allows management extensions to register resources and operations over a set of API's, which in turn allows us to expose these over common interfaces like REST and CLI. In other words, management extensions don't have to worry about the interfaces in which they will be managed over. This allows us to add additional interfaces without needing to change anything. Also by providing a set of API's to obtain managed resources, interfaces are built in a consistent manner. So managing the same component in one interface should be very similar if you were to manage it in another.

Operations

The following operations are operations that have been identified by the management component to be common to most management extensions. The read-resource operation is really the only global operation supported in the core framework, all other operations need to be implemented by the extensions, since these would be specific to each extension.

Operation Name Description                                                                                         
read-resource
The read-resource operation is responsible for reading the managed resource; describing itself and listing any operations and/or sub-resources it may contain.
This is the primary operation to obtain information about a managed component and it's managed resources.
add-resource
The add-resource operation is responsible for adding/creating additional managed resources.
remove-resource        
The remove-resource operation is responsible for removing/deleting an existing managed resource.
update-resource The update-resource operation is responsible for updating an existing managed resources state.
read-config-as-xml
The read-config-as-xml operation is responsible for representing the current managed resource as xml configuration.
export-resource
The export-resource operation is responsible for exporting a managed resource in a format that is acceptable and used in an import.  The export-resource is special in the
sense that there's built-in functionality to recursively traverse managed resources until it finds one that supports an export-resource operation.  In other words you can
register an export-resource operation on a sub-resource and it will be executed even by calling export-resource on any of it's ancestors.
import-resource
The import-resource operation is responsible for importing managed resources previously exported through an export-resource operation.

Content Type

Content type defines the format of management requests/responses. The three content types supported at the moment are json, xml, and zip. Since read-config-as-xml (xml), export-resource (zip), and import-resource (zip) are content type specific operations, the response must be in that format. Other then that it's up to the extension on which content type is supported for each operation.

Path Templates

Path templates are something that management extensions use to define dynamic content when registering resources. These path template variables are used during an export-resource to filter these managed resources. By specifying the filter attribute of an export-resource operation, managed resources can be explicitly included or excluded during export.

The filter attribute has the following value syntax:

Filter Syntax

where path-var is the path template variable name, name is the name of a managed-resource, and the '!' char, which is optional, is to exclude that resource rather then include it. Below are some examples that use the path template variable 'foo':

Only include managed resource 'bar'
Include managed resource 'bar' and 'foo-bar'
Exclude managed resource 'bar'
Exclude managed resource 'bar' and 'foo-bar'
Multiple path template variables (foo and baz) separated by the ';' char
Note
For more information on the usage of path templates specific to a management extension, see the management extensions section below.

REST

The management REST component is responsible for mapping restful requests to management requests. It does this by locating the managed resource by mapping the request URL to a management address and then invoking an operation on that managed resource. It defines an entry point for RESTful clients, and exposes the registered managed resources and operations over REST.

Entry Point

To gain access to management resources and operations over REST a RESTful client must know the entry point URL, which is defined as follows:

URL Syntax

Where the rest-context-name is the portal container's rest context name. So for the default portal, the rest context name is 'rest', and for a portal running on localhost and port 8080 the URL would be

URL Example
Note
The REST URL is protected, and the authenticated user must belong to the 'administrators' group of the portal.

Resource URLs

REST resource URLs are mapped to management addresses, and since every managed resource has a unique management address, every managed resource can be represented by a unique REST URL. The URL for identifying managed resources is as follows:

URL Syntax

The URL below uniquely identifies a managed resource named 'foo-bar', which is a sub-resource of 'bar', and 'bar' being a managed resource of the managed component 'foo'.

URL Example

Operations

To map a RESTful request to an operation the REST component must somehow map the HTTP request to an operation name. It can achieve this by looking at three things (in order of precedence):

  • HTTP URL Parameters
  • URL Extension
  • The HTTP method of the request.

HTTP Method

The following table shows which HTTP methods map to operation names.

HTTP Method        
Management Operation
GET
read-resource
PUT
update-resource
POST
add-resource
DELETE
remove-resource

This means that the same URL can invoke four different operations just by changing the HTTP method of the REST request.

Request Parameter

Since the management system supports more then just four operations, operations can also be explicitly defined by including HTTP parameters as part of the REST request. For example by adding the query parameter op to the request URL, clients can define what operation to invoke.

Custom operation defined in request parameter

It's best practice to use the HTTP method to dictate the operation name when it can. However nothing stops a client explicitly setting operation names as request parameters.

URL Extension

Sometimes it's nice to represent REST resources as files, so two URL extensions have been added to support two common operations: read-config-as-xml and export-resource. By adding the following URL extensions at the end of the URL, you can invoke these two operations.

URL Extension        
Management Operation
Example URL
.xml
read-config-as-xml
http://localhost:8080/rest/private/managed-components/foo/bar.xml
.zip
export-resource
http://localhost:8080/rest/private/managed-components/foo/bar.zip

This is just a convenient way to specify the operation name as a file extension instead of specifying it as a request parameter.

Attributes

Management attributes (which are part of a management request) are mapped by including all request parameters of the HTTP request as attributes. So if an operation supports certain attributes, query parameters can be added to the request URL to be used as attributes of the management request.

Attributes first-name and last-name as request parameters

Multi-value Attributes

Management attributes can be multi-valued (meaning more then one value associated with an attribute). This is easy as HTTP query parameters can be multi-valued as well.

Multi-valued attribute colors as request parameters

Content Negotiation

The management framework defines Content Type to indicate the format of management requests and responses. Clients can dictate the content type of the management request by specifying the Accept and Content-Type headers of the HTTP request. The Accept header indicates the format of the response and the Content-Type header specifies the format of the request. Below is a list of request headers that map to the Content Type of the management system.

Header        
Content Type
application/json
JSON
application/xml
XML
application/zip
ZIP
Note
JSON is the default content type.

Browser Content Negotiation

To make it easy to control the content type of management requests through the browser, the rest component supports the format HTTP parameter to dictate the format of the response. This is because most browsers already send an 'Accept' header.

Specifying the response should be returned as xml

Below is the list of format HTTP parameters which map to Content Types.

Format parameter      
Content Type
format=json (default)
JSON
format=xml
XML
Important
Content negotiation is ignored for content type specific operations such as 'read-config-as-xml' and 'export-resource' since these cannot return different formats.

read-resource

Since the read-resource operation is a built in operation provided by the management component, as opposed to extensions, below documents the format of the response.

HTTP Request
Response as JSON
Response as XML

Command Line Interface

The command line interface (CLI) component provides an interactive shell using CRaSH to map commands to management requests. It connects over SSH, using the CRaSH SSH plugin.

Note
For more information on CRaSH please visit http://code.google.com/p/crsh/.

Deploying the CLI

To deploy the CLI you must first build the gatein-management project. The source is available on github. Once built you can then deploy the web application to a GateIn instance like below:

Copy CLI artifact as an exploded war to application server
Important
The CLI web application must be deployed as an exploded war
The deployment method differs from the above in JBoss Enterprise Portal Platform. Refer to the documentation at [docs.redhat.com] for the appropriate deployment method for enterprise installations.

Running the CLI

After deploying the CLI web application you can connect to the CLI over SSH as follows

SSH Syntax
SSH Example

You can change the default port that SSH listens on by changing the property crash.ssh.port in the WEB-INF/crash/crash.properties file.

crash.properties
Important
Make sure the configured port is open and not blocked by firewall settings.

Commands

The CLI component comes with a number of management commands that will execute operations on managed resources in the portal. For a listing of all commands available type in help in the shell. You can also add the help option -h or --help for each command for further information. Also the man command can be executed for even more detailed information about the command.

mgmt

The mgmt command allows a user to connect and disconnect from the management system. It also provides an exec command which allows more custom control over executing operations with the management system.

mgmt help

The mgmt connect command allows the user to connect to the management system, optionally specifying a portal container (default is 'portal'). Since management commands are administrative operations, the user must authenticate again in order to validate authorization to the portal container.

Connecting to default portal container
Connecting to portal container 'sample-portal' as user john

The mgmt exec command allows complete control over what to send to the management system.

mgmt exec help
Executing operation read-config-as-xml on managed component foo

cat

The cat command executes the read-config-as-xml operation on a managed resource and outputs the xml data to the shell. Obviously the managed resource must support the read-config-as-xml operation.

cat help

cd

The cd command changes the current path of the CLI.

cd help
Change path to /foo/bar

ls

The ls command executes the read-resource operation on the current (or specified by the path) managed resource.

ls help

pwd

The pwd command prints out the current resource path of the CLI.

pwd help

export

The export operation executes the export-resource operation on a managed resource and writes the exported content to the file.

Important
Since the CLI is connected to the portal server over SSH, the export command will write to the servers file system, not the client.
export help
Export resource foo to /tmp directory
Note
If you only specify a directory the export command will write a file with the name of the managed resource and a timestamp.
Export resource /foo to /tmp/export-example.zip file
Export resource filtering on path template variable bar

import

The import command executes the import-resource operation on a managed resource.

import help
Important
Since the CLI is connected to the portal server over SSH, the import command must specify a file that exists on the server.
Import file /tmp/foo.zip to resource foo
Import file /tmp/foo.zip to resource foo using importMode overwrite
Note
You can autocomplete the import modes by typing --importMode and hitting tab.

Secure Copy (SCP)

The CLI application supports SCP to execute the export-resource and import-resource operations in order to export to and import from a host other then the portal.

Export

To execute the export-resource operation using SCP the source of the SCP command is the portal server and the target is the local file to export to.

Syntax

The portal-container is optional with default value being 'portal'. The path is the path of the resource supporting the export-resource operation.

So to export 'foo/bar' resource assuming the CLI is deployed to 'example.org'.

Export of foo/bar resource

Attributes like 'filter' can be added to the path of the SCP command just as you would add query parameters to a URL.

Export of foo/bar resource with filter

Import

To execute the import-resource operation using SCP the source of the SCP command is the local file and the target is the portal server.

Syntax

The portal-container is optional with default value being 'portal'. The path is the path of the resource that supports the import-resource operation. So to import a foo.zip file to the /foo resource assuming the CLI is deployed to 'example.org'.

Import foo.zip to foo resource
Note
More specific examples of the SCP command can be found below pertaining to that particular management extension.

Management Extensions

The following management extensions supported in the portal are:

  • MOP Management Extension

MOP Management Extension

The MOP management extension registers the 'mop' managed component which is responsible for managing pages, navigation, and site layout. It primarily supports exporting and importing this data through the export-resource and import-resource operations. It also supports the read-config-as-xml operation to expose the portal meta data as xml.

Operations

read-config-as-xml

The read-config-as-xml operation can only be executed on the site layout, pages, and navigation managed resources. The xml format returned is that of which is defined in by the gatein-objects xsd. This means that these resources are exposed in the same format as what a portal extension would accept for importing data into the portal.

export-resource

The export-resource operation can be executed on any resource of the MOP extension (including the mop component itself). Since the management system recursively searches for all sub-resources that have export-resource defined (which they are defined at the site layout, page, and navigation level), exports can be very granular.

import-resource

The import-resource operation can only be executed at the mop component (root managed resource of the mop extension). This is because the exported zip file contains the path information (like site type and site name). So executing an import-resource operation on a group site, when the zip contains data from a portal site, doesn't make sense.

The MOP import-resource operation defines the importMode attribute as follows during import.

Mode
Description
conserve
Import data only if no artifacts exist for that site. For example if one page exists for site 'classic', nothing will be imported.
insert
Import data when data does not exist, otherwise do nothing.
merge
Import when data does not exist, update data when it does exist.
overwrite
Delete all data for that artifact of the site, import new data. For example if the zip file only contains pages for site classic, then
all pages for that site are deleted and imported.
Note
'merge' is the default importMode.

Path Templates

Below are the list of path template variables defined in the MOP management extension. These path template variables are used for filtering during export.

  • site-type
    These are the site types of the portal to include or exclude. Available values are: portal, group, and user.
  • site-name
    The sites to include or exclude. Examples could be classic and /platform/administrators.
  • site-layout
    The name of the site layout depending on the site type. Available values are: portal, group, user.
  • page-name
    The name of the page(s) to include or exclude.
  • nav-uri
    The URI of the navigation node to include or exclude.

REST API

Note
All URL's below are relative to the REST management entry point of the portal container.
Note
For all read-config-as-xml refer http://www.gatein.org/xml/ns/gatein_objects_1_2 for the format of the XML.

MOP Component Resource

The mop managed component resource (root managed resource) is the only resource that accepts the import-resource operation.

HTTP Request
HTTP Response

Site Layout Resource

The site layout resource represents the site layout of the portal. It's the data defined in the portal.xml, group.xml, and user.xml files (depending on site type) used in portal extensions to configure data.

URL
read-config-as-xml

Example of reading the site layout as xml for site classic.

HTTP Request
HTTP Response
export-resource

Example of exporting the site layout for site classic.

HTTP Request
HTTP Response

Pages Resource

The pages resource represents the pages of the portal. It's the data defined in the pages.xml used in portal extensions to configure data.

URL
read-config-as-xml

Example of reading all pages as xml for site classic.

HTTP Request
HTTP Response

Example of reading the homepage as xml for site classic.

HTTP Request
HTTP Response
export-resource

Example of exporting all pages of site classic.

HTTP Request
HTTP Response

Navigation Resource

The navigation resource represents the navigation of the portal. It's the data defined in the navigation.xml used in portal extensions to configure data.

URL
read-config-as-xml

Example of reading all navigation as xml for site classic.

HTTP Request
HTTP Response

Example of reading the home node as xml for site classic.

HTTP Request
HTTP Response
export-resource

Example of exporting all navigation of site classic.

HTTP Request
HTTP Response

Export and Filtering

Filtering is activated when the filter attribute is passed to an export-resource operation. The filter attribute is a multi-value attribute that is passed as request parameters of the HTTP request.

Note
You can either include multiple filter parameters (?filter=foo:bar&filter=baz:foo-bar) or separate via ';' character (?filter=foo:bar;baz:foo-bar)
Export only registry and pageManagement navigation nodes
Export all site types but user and group

Command Line Interface

The commands included in the management component provide us the tools to perform management operations on these MOP artifacts: site layout, pages, and navigation.

Resource Paths

The paths of the MOP resources are exactly the same as the REST URL's (of course without the URL syntax). For example the path of the homepage for the classic site would be:

Example
Note
All resources/paths can be autocompleted by hitting the tab key.

Export and Filtering

Filtering is activated when the filter attribute is passed to an export-resource operation. The filter attribute is a multi-value attribute that is passed to the CLI using the --filter attribute for the export command.

Export all portal site types
Export all sites types but user

The option can be specified multiple times for multiple values.

Export only the /platform/administrators group site

Also as discussed in the Path Templates section in this document, the filter attribute can separate different path templates by the ; character.

Export only pages named homepage, navigation named home for site classic
Important
All three artifacts (site layout, navigation, and pages) are included in export by default. In other words if you don't specify their path template in the filter, the data will be included.

Secure Copy (SCP)

The SCP command can be used to export and import MOP artifacts: site layout, pages, and navigation over different hosts. The following examples will assume the portal and CLI is running at host 'example.org' with default ssh port configured to 2000.

Since the export-resource command is supported on all resources of the MOP extension, below are just some examples.

Export MOP artifacts

The import-resource operation is only supported at the mop resource, so for every import the path must be '/mop'.

Import MOP artifacts
Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.