JMX/REST Management¶

In this chapter, the following topics are included:

Introduction to eXo Platform management Overall information about managing resources of eXo Platform, JMX and REST interfaces.

Management views of eXo Platform Introduction to the following set of management view types of eXo Platform and their Object Names:

PortalContainer management view

Cache management view

Content management view

JCR management view

Portal management view

Forum management view

Jobs and Job Scheduler List of the Cron Jobs and the Job Scheduler MBean.

eXo Platform notifications monitoring A step by step to monitor notifications.

Introduction to eXo Platform management¶

Managing resources of eXo Platform is critical for IT operators and system administrators to monitor and supervise the production system. eXo Platform can be managed using JMX (Java Management Extension) tools or REST service.

To use JMX, some settings are required. To use REST service, you just need a browser. As you will see later in this chapter, all operations are available in JMX and some of them are available in REST. So use JMX if you need all operations and use REST in some cases, for example, you are on a machine that JMX is not installed, or at remote region where JMX is inaccessible because of security setup.

How to manage eXo Platform with JMX¶

JMX and JMX Client

Note

See Oracle’s Documentation to learn about JMX (Java Management Extension).

To manage eXo Platform with JMX, you need a JMX Client, or more exactly an MBean Browser. JConsole is a built-in tool, and it features an MBean browser, so it does not require any installation. Another suggestion is VisualVM, which requires some steps to install its MBean plugin.

The tools are graphical and you may just try and use to explore MBean. In this chapter, the following terms will be used to describe an individual or a group of similar MBeans:

Object Name is used to identify and indicate an MBean. All MBeans introduced in this chapter can be found under a group “exo”, however their organization may make it difficult to find an MBean. For example, you will see three groups with the same name “portal”, so this document will not indicate an MBean by its position in the MBeans tree, but by its Object Name.

If you are using VisualVM, you can see Object Name in the “Metadata” tab.
Attribute is a pair of “Name” and “Value”. A list of Attributes shows the state of an MBean object.
Operation is a function that you can invoke. Each MBean provides some (or no) Operations. Some Operations are “Set” and some Operations are “Get”. An Operation may require data inputs.

Configuring eXo Platform to allow JMX access

The JMX configurations are JVM options and thus basically not specific to eXo Platform. Such configurations are explained at Oracle’s Documentation.

In eXo Platform, by default JMX is not configured. Thus, local access is enabled and remote access is disabled. Authentication is disabled as well, this means username and password are not required. If you want to enable remote access or authorization, you need to start customizing eXo Platform, as instructed in the Customizing environment variables section.

After the start, put your JMX configurations in the form described in Advanced Customization <AdvancedCustomization> section.

Securing JMX connection

It is recommended to enable security for production system. You may:

Enable SSL. See Using SSL.
Enable Password Authentication. See Using Password Authentication and Using Password and Access Files.

How to manage eXo Platform with REST service¶

Using REST service, you can do some operations with a browser. It requires no setup.

You need to be member of /platform/administrators to access REST services.

You also need to know the URL of a service (or its attributes and operations) to access it. You can get the URLs as follows:

Enter the base URL: http://[your_server]:[your_port]/rest/private/management, which is to access all management REST services, in your browser, then log in. The page returns a list of available REST services in plain text.
Select a service name and append it to the base URL. You will have the service’s URL, for example: http://[your_server]:[your_port]/rest/private/management/skinservice. Entering this URL, you will get a list of attributes (as “properties”) and operations (as “method”).
Continue appending an attribute of Step 2 to have URL of a method or property. Let’s see the “skinservice” as an example:
- Its property “SkinList” can be accessed by the URL: http://[your_server]:[your_port]/rest/private/management/skinservice/SkinList.
- Its method “reloadSkins” can be invoked by the URL: http://[your_server]:[your_port]/rest/private/management/skinservice/reloadSkins.
- The URL of the method “reloadSkin” is a bit complex because the method requires parameter “skinId” (to know which Skin will be reloaded): http://[your_server]:[your_port]/rest/private/management/skinservice/reloadSkin?skinId=Default.

Management views of eXo Platform¶

PortalContainer management view The management view of all objects and configurations of a given portal.
Cache management view The management view of eXo Platform caches at several levels that provides the critical performance information, especially useful for tuning the server.
Content management view The management view of WCMService.
JCR management view The management view of SessionRegistry, LockManager, Repository, and Workspace that allow you to monitor sessions, locks, repository configurations, and workspace configurations respectively.
Portal management view A set of the Portal management views, including Template statistics, Template service, Skin service, TokenStore, Portal statistics, and Application statistics.
Forum management view A set of the Forum management views, including Forum, Job, Plugin, Storage that allows you to control rules, statistics, information of data storage.

PortalContainer management view¶

PortalContainer manages all objects and configurations of a given portal.

The Object Name of PortalContainer MBeans: exo:container=portal,name=portal.

Attribute	Description
`ConfigurationXML`	Configuration information of the specified portal container in the XML format.
`Name`	The name of the portal container.
`RegisteredComponentName s`	The list of the registered component names.
`Started`	Indicates if the portal container is started or not.

Operation	Description
`getConfigurationXML`	Returns configuration information of the portal container calculated by the loading mechanism. The returned value is an XML document in the eXo Kernel format.
`getName`	Returns the portal container name.
`getRegisteredComponentN ames`	Returns the list of all registered component names.
`isStarted`	Checks if the portal container is started or not. The portal container is only started once all its components have been started.

Note

PortalContainer can be controlled through the following path: - http://mycompany.com:8080/rest/management/pcontainer.

Cache management view¶

eXo Platform uses caches at several levels. Monitoring them can provide the critical performance information, especially useful for tuning the server. Each cache is exposed with statistics and management operations.

CacheService¶

There are many Cache MBeans of which the Class Name is common: org.exoplatform.services.cache.concurrent.ConcurrentFIFOExoCache and the Object Names are: exo:service=cache,name={CacheName} where CacheName is specified for each MBean.

Attribute	Description
`Name`	The name of the cache.
`MaxNodes`	The maximum capacity (nodes) of the cache.
`HitCount`	The total number of times the cache was successfully queried.
`MissCount`	The total number of times the cache was queried without success.
`Size`	The number of entries in the cache.
`TimeToLive`	The valid period of the cache in seconds. If the value is set to -1, the cache never expires.

Operation	Description
`clearCache()`	Evicts all entries from the cache. This method can be used to force a programmatic flush of the cache.
`getName`	Returns the cache name.
`getLiveTime`	Returns the valid lifetime of an entry in the cache in seconds.
`setLiveTime`	Sets the valid lifetime of an entry in the cache in seconds.
`getCacheHit`	Returns the total number of successful hits.
`getCacheMiss`	Returns the total number of unsuccessful hits.
`getMaxSize`	Returns the maximum capacity of the cache.
`setMaxSize`	Sets the maximum capacity of the cache.
`getCacheSize`	Returns the number of entries in the cache.

CacheManager¶

The CacheManager MBean has no attribute and only one method to clear all the Caches.

The Object Name of CacheManager Mbeans: exo:service=cachemanager.

Operation	Description
`clearCaches()`	Forces a programmatic flush of all the registered caches.

PicketLinkIDMCacheService¶

PicketLinkIDMCacheService is the default implementation for the organization model. It has no attribute.

The Object Name of PicketLinkIDMCacheService MBean: exo:portal=”portal”,service=PicketLinkIDMCacheService,name=plidmcache.

Operation	Description
`invalidateAll`	Invalidates all cache entries.
`invalidate(namespa ce)`	Invalidates a specific cache namespace.
`printCaches`	Lists out all cache entries.

Note

PicketLinkIDMCacheService can be controlled through the following path:

http://mycompany.com:8080/rest/management/plidmcache.

However, the REST View managements of CacheService and CacheManager are not currently exposed in this version.

Content management view¶

WCMService¶

The Object Name of WCMService MBean: exo:portal=portal,service=wcm,view=portal,type=content.

Attribute	Description
`PortletExpirationCac he`	The expiration period of portlet cache in seconds.

Operation	Description
`getPortletExpiration Cache`	Returns the expiration period of portlet cache in seconds.
`setPortletExpiration Cache (expirationCache )`	Sets the expiration period of portlet cache by entering the value into the expirationCache field.

Note

WCMService can be controlled through the following paths respectively: - http://mycompany.com:8080/rest/management/wcmservice/.

JCR management view¶

Java Content Repository (JCR) provides a management view to monitor sessions, locks, repository configurations, and workspace configurations.

Repository¶

The Object Name of Repository MBean: exo:portal=portal,repository=repository.

Attribute	Description
`Name`	The name of the repository container.
`RegisteredComponentName s`	The list of registered component names in the repository.

Operation	Description
`getName`	Returns the repository container name.
`getRegisteredComponentN ames`	Returns the list of registered component names in the repository.

SessionRegistry¶

The Object Name of SessionRegistry MBean: exo:portal=portal,repository=repository,service=SessionRegistry.

Attribute	Description
`TimeOut`	The expiration period of a JCR session.
`Size`	The number of currently active sessions.

Operation	Description
`runCleanup`	Cleans all JCR sessions timed out.
`getTimeOut`	Returns the session timeout.
`setTimeOut`	Sets the session timeout in seconds.
`getSize`	Returns the number of currently active sessions.

Workspace¶

There are several default workspaces listed below, each of them corresponds to a Workspace MBean:

Workspace Name	Description
`collaboration`	Data, such as sites content, documents, groups, records space, tags, and users.
`dms-system`	Data of DMS, including node types, templates, views, taxonomy trees.
`knowledge`	Data of Forum, FAQ and Poll applications.
`portal-system`	Data of the Portal model objects, such as navigations, pages, sites, and application registry.
`portal-work`	Information of Gadget token and Remember me token.
`social`	Data of Social, including activity, identity, profile, relationship and space.
`system`	Data of system, including versions storage, node types, namespaces.

The Object Name of Workspace MBeans: exo:portal=portal,repository=repository,workspace={WorkspaceName} where WorkspaceName is the name of each workspace.

Attribute	Description
`Name`	The name of the workspace container.
`RegisteredComponentNam es`	The list of registered component names in the workspace.

Operation	Description
`getName`	Returns the workspace container name.
`getRegisteredComponent Names`	Returns the list of registered component names in the workspace.

LockManager¶

Each Workspace has an MBean to manage locks.

The Object Name of LockManager MBeans: exo:portal=portal,repository=repository,workspace={WorkspaceName},service=lockmanager where WorkspaceName is the name of each workspace.

Attribute	Description
`NumLocks`	The number of active locks.

Operation	Description
`cleanExpiredLock s`	Removes all expired JCR locks.
`getNumLocks`	Returns the number of active JCR locks.

Note

Currently, the REST View managements of SessionRegistry,: LockManager, Repository and Workspace are not exposed in this

version.

Portal management view¶

Template statistics¶

Template statistics exposes various templates used by the portal and its components to render markups. Various statistics are available for individual templates, and aggregated statistics, such as the list of the slowest templates. Most management operations are performed on a single template; those operations take the template identifier as an argument.

The Object Name of Template statistics MBean: exo:portal=portal,service=statistic,view=portal,type=template.

Attribute	Description
`TemplateList`	The list of templates loaded.
`SlowestTemplates`	The list of the 10 slowest templates.
`MostExecutedTemplat es`	The list of the 10 most used templates.
`FastestTemplates`	The list of 10 fastest templates.

Operation	Description
`getAverageTime(template Id)`	Returns the average rendering time of a specified template in seconds.
`getExecutionCount(templ ateId)`	Returns the number of times executed by the specified template.
``getMinTime(templateId)` `	Returns the minimum rendering time of the specified template in seconds.
``getMaxTime(templateId)` `	Returns the maximum rendering time of the specified template in seconds.
`getSlowestTemplates`	Returns the list of the 10 slowest templates.
`getMostExecutedTemplate s`	Returns the list of the 10 most used templates.
`getTemplateList`	Returns the list of templates loaded.
`getFastestTemplates`	Returns the list of the 10 fastest templates.

Template management¶

Template management provides the capability to force the reload of a specified template.

The Object Name of Template management MBean: exo:portal=portal,service=management,view=portal,type=template.

Operation	Description
`reloadTemplates`	Clears the template cache.
``listCachedTemplates` `	Lists identifiers of the cached templates.
`reloadTemplate(templ ateId)`	Clears the template cache for a specified template identifier.

Skin management¶

The Object Name of Skin management MBean: exo:portal=portal,service=management,view=portal,type=skin.

Attribute	Description
`SkinList`	The list of loaded skins by the skin service.

Operation	Description
`reloadSkin(skinId )`	Forces a reload of the specified skin and the operation.
`reloadSkins`	Forces a reload of the loaded skins.
`getSkinList`	Returns the list of loaded skins by the skin service.

TokenStore¶

The Object Name of TokenStore MBeans: exo:portal=portal,service=TokenStore,name={Name} where Name is the name of each specific token.

Attribute	Description
`Name`	The name of one specific token.
`ValidityTime`	The expiration period of one specific token in seconds.
`PeriodTime`	The expiration daemon period of one specific token in seconds. The token is deleted after the specified period.

Operation	Description
`cleanExpiredToken s`	Removes all expired tokens.
`size`	Returns the number of tokens, including valid tokens and expired tokens undeleted yet.
`getName`	Returns the token name.
`getValidityTime`	Returns the expiration time of one specific token in seconds.
`getPeriodTime`	Returns the expiration daemon period of one specific token in seconds.

eXo Platform provides the following TokenStore instances:

Token Name	Description
`gadget-token`	Stores tokens of the Oauth gadget into the JCR node, such as org.exoplatform.portal.gadget.core.Gadget TokenInfoService.
`jcr-token`	Stores common tokens into the JCR node, such as org.exoplatform.web.security.security.CookieTokenS ervice, and org.exoplatform.web.security.security.RemindPasswo rdTokenService.

Portal statistics¶

The Object Name of Portal statistics MBean: exo:portal=portal,service=statistic,view=portal,type=portal.

Attribute	Description
`PortalList`	The list of identifiers of loaded portals.

Operation	Description
`getThroughput(portalId )`	Returns the number of requests for the specified portal per second.
`getAverageTime(portalI d)`	Returns the average execution time of the specified portal in seconds.
`getExecutionCount(port alId)`	Returns the number of times the specified portal has been executed.
`getMinTime(portalId)`	Returns the minimum time of the specified portal in seconds.
`getMaxTime(portalId)`	Returns the maximum time of the specified portal in seconds.
`getPortalList`	Returns the list of identifiers of loaded portals.

Application statistics¶

Various applications are exposed to provide relevant statistics.

The Object Name of Application statistics MBean: exo:portal=portal,service=statistic,view=portal,type=application.

Attribute	Description
`ApplicationList`	The list of loaded applications.
`SlowestApplications`	The list of the 10 slowest applications.
``MostExecutedApplications` `	The list of the 10 most executed applications.
`FastestApplications`	The list of the 10 fastest applications.

Operation	Description
`getAverageTime(applicatio nId)`	Returns the average time spent of the specified application.
`getExecutionCount(applica tionId)`	Returns the number of times the specified application has been executed.
``getMinTime(applicationId) ``	Returns the minimum time spent of the specified application.
``getMaxTime(applicationId) ``	Returns the maximum time spent of the specified application.
`getSlowestApplications`	Returns the list of the 10 slowest applications.
`getMostExecutedApplicatio ns`	Returns the list of the 10 most executed applications.
`getFastestApplications`	Returns the list of the 10 fastest applications.
`getApplicationList`	Returns the list of application identifiers classified in the alphabetic order.

Note

Template statistics, Template management, Skin management, Portal statistics and Application statistics can be controlled through the following paths respectively:

http://mycompany.com:8080/rest/management/templatestatistics

http://mycompany.com:8080/rest/management/templateservice

http://mycompany.com:8080/rest/management/skinservice

http://mycompany.com:8080/rest/management/portalstatistic

http://mycompany.com:8080/rest/management/applicationstatistic

However, the REST View management of TokenStore is currently not exposed in this version.

Forum management view¶

Some MBeans are provided to manage Forum application.

Forum¶

The Object Name of Forum MBean: exo:portal=portal,service=forum.

Attribute	Description
`AdminRules`	The list of rules defining administrators.
`ContactProvider`	The string containing the specific ContactProvider implementation name which provides user profile to the forum.
`MailServiceConfig`	The string containing the configuration of the Mail service used for the notifications in Forum.
`OnlineUsers`	The list of currently online users.

Operation	Description
`countOnlineUsers`	Returns the number of currently online users.
`hasForumAdminRole(St ring username)`	Checks if the user is the forum administrator or not.
`getAdminRules`	Returns the list of rules defining administrators.
`getOnlineUsers`	Returns the list of online users.
`getContactProvider`	Returns the name of a specific ContactProvider implementation.
`setContactProvider(S tring contactProviderC lassName`	Sets ContactProvider implementation.
``getMailServiceConfig ``	Returns the Mail service configuration used to send notifications in Forum.

Jobs¶

The Object Name of Forum Job MBeans: exo:portal=portal,service=forum,view=jobs,name={Name} where Name is specified for each job (listed later).

Attribute	Description
`DataMap`	The map containing the state information for Job instances.
`JobClassName`	The FQDN of the job.
`Name`	The name of the Job.

Operation	Description
`getName`	Returns the names of Job instances.
``getJobClassName` `	Returns the FQDN of the job.
`getDataMap`	Returns the state information of Job instances.

The list of Forum Jobs:

Job	Description
`DeactiveJob`	Deactivates topics which meet TWO predefined deactivation properties: inactiveDays and forumName in Forum.
`DelayWritesJob`	Updates the view count of topics and the list of viewers.
`LoginJob`	Updates information of users logged in, serving for statistics.
`RecountActiveUse rJob`	Indicates the number of active users in Forum.
`SendMailJob`	Sends email notifications in Forum.

RoleRulesPlugin¶

The Object Name of RoleRulesPlugin MBean: exo:portal=portal,service=forum,view=plugins,name=”add.role.rules.plugin”.

Attribute	Description
`AllRules`	The list of all rules of RoleRulesPlugin. For example, the rule defining ‘root’ user as an administrator follows the form of ADMIN=root.
`Description`	The brief description of RoleRulesPlugin functions.
`Name`	The name of RoleRulesPlugin.
`RuleNames`	The list of possible rule names; for example, the rule defining administrators is named ADMIN.

Operation	Description
`addRule`	Adds a rule. For example, to add the ADMIN rule for a user, you need to input two parameters: “ADMIN” in the p1 and user name in the p2.
`getRules`	Returns the list of rules defining the user with the role inputted in p1.
`getName`	Returns the name of the plugin.
`getRuleNames`	Returns the list of possible rule names. For example, if ‘user1’ and ‘user2’ are defined as ADMIN (ADMIN=user1, user2), the list of returned rule names will be ADMIN.
`getDescription`	Returns the brief description of the plugin.
`getAllRules`	Returns all rules added to the plugin.

Storage¶

This MBean enables you to get storage information (data path, repository, workspace) of Forum application.

The Object Name of Forum Storage MBean: exo:portal=portal,service=forum,view=storage.

Attribute	Description
`Path`	The JCR data path of the Forum Storage.
`Repository`	The name of repository containing the workspace where Forum data is stored.
`Workspace`	The name of workspace containing Forum data.

Operation	Description
`getRepository`	Returns the name of repository of the Forum Storage.
`getWorkspace`	Returns the name of workspace of the Forum Storage.
`getPath`	Returns the JCR data path of the Forum Storage.

Note

Currently, the REST View managements of Forum, Job, Plugin, Storage are not exposed in this version.

Jobs and Job Scheduler¶

Jobs are components that run in background and perform scheduled tasks, such as sending notification emails every day.

In eXo Platform, jobs are managed by Quartz Scheduler. This framework allows to schedule jobs using simple patterns (daily, weekly) and Cron expressions.

The following tables are the jobs and their default configuration:

Name	Description	Schedule
changeStateJobToPubli shed (Content)	Scans collaboration:/sites for awaiting content and publishes them.	Every 2 minutes
changeStateJobToUnpub lished (Content)	Scans collaboration:/sites for awaiting content and unpublishes them.	Every 2 minutes
NotificationWeeklyJob	Sends weekly notification.	11 am, every Sunday
NotificationDailyJob	Sends daily notification.	11 pm, every day
WebNotificationJob	Cleans the web notifications that are older than 30 days.	On the 23rd of every month
ReminderJob (Calendar)	Searches for incoming events and sends email reminders.	Every 15 seconds
PopupReminderJob (Calendar)	Searches for incoming events and shows popup reminders.	Every 15 seconds
periodically (Forum)	Saves forum statistic data.	Every 12 hours
SendMailJob (Forum)	Sends email notification in Forum.	Every 2 minutes
DelayWritesJob (Forum)	Updates view count of topics.	Every 1 minute
DeactiveJob (Forum)	Watches a forum and deactivates the topics that have no post for a period. Currently it is configured to a non-existing forum.	Every 2 hours
RecountActiveUserJob (Forum)	Updates statistic of active users (who have posted in the last 15 days).	Every 2 hours
LoginJob (Forum)	Updates information for users who are currently logged in.	Every 2 minutes

You can suspend or resume the jobs via JMX. Find the MBean exo:portal=portal,service=JobSchedulerService like in the screenshot, it gives you the two operations.

eXo Platform notifications monitoring¶

Monitoring is a means to be aware about your system’s state. You can monitor different parts of eXo Platform through JConsole.

To monitor and observe notification settings in eXo Platform, you should follow these steps:

In the file exo.properties, add this property exo.social.notification.statistics.active and set it to true.
Start your server and then open a new terminal to start JConsole using the command jconsole.
Go to MBeans tab.
Navigate in the tree to exo –> portal –> notification –> statistic to get statistics about eXo Platform notifications.