Skip to end of metadata
Go to start of metadata

ModeShape is not included with JBoss Wildfly, so none of the standard configurations include any ModeShape configurations. However, once ModeShape is installed into Wildfly, it's easy to add ModeShape to any Wildfly configuration.

Since the number of ModeShape configuration elements for Wildfly is very large, this page only provides some general configuration guidelines. For a full list of elements & attributes we encourage reading/using the latest version of the ModeShape XML schema, which is part of the kit and is located in the docs/schema folder.

Step 1: Start the server

Start your server in standalone mode with your favorite configuration. For example, the following starts with the "standalone.xml" configuration file:

Use the appropriate command for your OS. See the Wildfly documentation for details.

Step 2: Start the server's CLI

JBoss Wildfly has a very nice low-level command line interface (CLI) tool that you can use to directly manipulate the configuration of the running server. If the server is running in domain mode, the CLI will immediately propagate the changes to all the servers.

Start the CLI and connect to your server:

Step 3: Add the ModeShape subsystem

ModeShape is installed, but the current configuration doesn't know about the ModeShape subsystem. So the next step is to add it:

The configuration's XML file (in this case "standalone.xml") is updated immediately. Watch the configuration file as you use the CLI.

Step 4: Add a ModeShape repository

We want to add a repository, but before we do that we need to add or configure the Wildfly resources that the repository will use.

Step 4a: Add an Infinispan cache

Starting with ModeShape 4.3 this cache configuration is no longer supported. See this

Each ModeShape repository stores its content in an Infinispan cache. But let's put that cache in a new cache container named "modeshape", which we can use for other repositories:

The CLI supports tab-completion, so as you type out these paths try hitting tab to have the CLI fill out as much as possible or show the available matches.

Now that we have our container, we'll define a local cache named "sample" (which by convention we'll name the same as our repository, although this is not required) that uses non-XA transactions and persists all content immediately to the "modeshape/store/sample" directory under the "standalone/data" directory:

Most of the commands we've issued so far resulted in a simple successful outcome. The last two, however, were successful but apparently require a reload of the Infinispan service. That basically means that our changes were saved to the configuration, but the last two changes won't take effect until the next restart or until we explicitly perform the reload (which we'll do twice):

Step 4b: Add a security domain

ModeShape can use any security domain, as long as the domain defines the correct ModeShape roles for each user. Since none of the out-of-the-box security domains includes these roles, let's create our own security domain that uses 2 properties files: and files which should be included in the "module/org/modeshape/main/conf" directory:

Again, we need to reload the services for these changes to take effect:

This security domain represents the most simple security domain with which you can configure ModeShape and is different than the default security domain from the ModeShape kit. See this for more information.

JBoss Wildfly supports multiple kinds of security domains, including integration with LDAP and even single sign-on using the local OS. Consult the JBoss Wildfly documentation for details.

Step 4c: Add the repository

Starting with ModeShape 4.3 the cache-container attribute is no longer supported. See this

Now that we've finished defining the services that our repository will use, we can define our ModeShape "sample" repository:

This command configures the repository to use the "sample" Infinispan cache in the "modeshapce" cache container, and to use the "modeshape-security" security domain we created earlier.

We actually didn't need to define the security-domain="modeshape-security" attribute because the repository would use a security domain with that name by default. Also, by default the repository will try to use an Infinispan cache with the same name as the repository in the cache container named "modeshape". Specifying them doesn't hurt, but any attributes that match the default value will not be serialized to the XML configuration file.

Note that defining a repository doesn't require restart. In fact, quite a few of the ModeShape administrative operations can take effect immediately, even when applications are actively using the repository.

Advanced configuration

With just a few commands, you can add a repository that will persist content locally. However, more advanced configuration options are available.

Advanced repository configuration

At any point, we can see the complete definition of a repository:

This shows all of the attributes, including those that are not set or set to their default values. To see more detail about each attribute and child, use the ":read-resource-description()" command:

We didn't show all of the output, since it's quite long. But each attribute is described and shows the criteria for valid values, whether expressions (e.g., system variables) are allowed, and whether a restart will be required before changes take effect.

Most of the attributes do have defaults, but some of these defaults are not listed in the descriptions because the defaults are functions of other attributes. For example, every repository is registered in JNDI under "jcr/repositoryName", and also under the JNDI name explicitly set with the "jndi-name" attribute.

The following table contains the list of all the attributes for a repository:

Attribute Name Description
allow-workspace-creation Specifies whether authenticated and authorized JCR users can create additional workspaces beyond the predefined, system, and default workspaces. The default value is 'true'. Set this to 'false' when the workspaces are to be fixed.
anonymous-roles The list of string names of the roles for all anonymous users. Anonymous logins will be disabled if the roles consists of an empty string. By default, anonymous users are given all roles: 'connect', 'readonly', 'readwrite', and 'admin'.
anonymous-username The username for all anonymous users. The username '<anonymous>' is used by default (that is, 'anonymous' surrounded by angle brackets").
cache-container The name of the Infinispan cache container in which the cache can be found. If not provided, the "modeshape" cache container will be used. Removed starting with ModeShape 4.3
cache-name The name of the Infinispan cache where repository content will be stored.If not provided, the repository name is used for the cache name.
default-workspace The name of the workspace that should be used when Sessions are created without specifying an explicit workspace name. By default, the "default" workspace name is used.
enable-monitoring Specifies whether the repository is to maintain the metrics that can be used to monitor the performance and activities. The default value is 'true', meaning monitoring is enabled.
jndi-name The repository will always be bound in JNDI to the name 'jcr/{repositoryName}', but this attribute can be used to specify an additional location in JNDI where the repository is to be registered.
minimum-binary-size The size threshold that dictates whether String and binary values should be stored in the binary store. String and binary values smaller than this value are stored with the node, whereas string and binary values with a size equal to or greater than this limit will be stored separately from the node and in the binary store, keyed by the SHA-1 hash of the value. This is a space and performance optimization that stores each unique large value only once. The default value is '4096' bytes, or 4 kilobytes.
predefined-workspace-names The names of the workspaces that the repository will ensure exist (or create if necessary) when the repository starts up.
security-domain The name of the security domain that should be used for JAAS authentication. The default is 'modeshape-security'
use-anonymous-upon-failed-authentication Indicates that failed authentication attempts will not result in a javax.jcr.LoginException but will instead fall back to anonymous access. If anonymous access is not enabled, then failed login attempts will throw a LoginException. The default value is 'false'.
The file which should be treated as the default initial content imported into all workspace. See initial content for more information
A set of (workspaceName, initial content file) pairs, which defined the custom initial content files for each workspace. See initial content for more information
A sequence of node-type elements, where the value of each element represents a path to a CND file which should be imported at repository startup. See registering custom node types for more information
A sequence of source elements, where each element contains the definition of an external source

At this point, any deployed application can use the repository (see the the chapter) for details).

Add and remove sequencers

You can use the CLI to dynamically add and remove sequencers. Here's an example that adds to the "sample" repository a sequencer that operates against comma-separated value (CSV) files uploaded under the "/files" node:

Note how this particular sequencer has an additional "splitPattern" property that specifies the delimiter.

To remove a sequencer, simply invoke the "remove" operation on the appropriate item:

Specify indexing configuration


Specify where large binary values are stored

In the same way you specify index storage above, you first need to add the binary storage resource to your configuration:

Once the binary storage node is added, you can add the storage type with required/optional parameters:

If you configure binaries to be stored on disk, the path attribute from above always represents *a relative path* to the by default. You can specify another root directory by using the relative-to attribute.

Configuring a composite binary store

Composite binary stores are different from the rest of the standard binary stores, because they can aggregate any number of standard binary stores. Therefore configuring them via CLI is a bit different.

First, you need to configure the composite binary store in similar fashion to any other binary store:

After this, you need to make sure that each nested store has a store-name property which is unique within the composite store and that the appropriate resource-container is used when adding the store.

Corresponding to each of the standard binary stores, the following resource-containers are available:

  • nested-storage-type-file - for file system binary stores
  • nested-storage-type-cache - for cache binary stores
  • nested-storage-type-db - for database binary stores
  • nested-storage-type-custom - for custom (user defined) binary stores

For example, if you wanted to add a file system binary store to a composite store, you would run:

If you wanted to remove this store, you would run:

Add and remove authentication and authorization providers

You can use the CLI to dynamically add and remove custom authentication and authorization providers. For example, if your implementation were named "org.example.MyAuthProvider" and were added to a new "org.example.auth" module, then the following command would add this provider to the "sample" repository:

To remove an authentication provider, simply invoke the "remove" operation on the appropriate item:

ModeShape can set instance-level fields on the provider instances. For example, you might want to set the "auth-domain" field on the MyAuthProvider instance to the String value "global". To do this, simply add them via the "properties" parameter (which is a list of documents that each contain a single name-value pair):

When running in JBoss AS, ModeShape will always use some built-in security providers required in order to integrate with the application server's security domain (see Step 4b: Add a security domain). This means that these providers will always be invoked during the authentication / authorization process for any given user. However, when adding custom providers to the configuration, ModeShape will place those first in the list of authentication providers. So if you want to avoid defaulting to the built-in security providers, make sure your custom providers always decide if a user is authenticated or not.

Add JDBC Data Source

First, you need to add the driver:

Then, the actual datasource:

Add and remove external sources

To enable federation, one or more external sources can be added to an existing repository.

The following example show how using the CLI an external file system source (via the FileSytemConnector) can be linked to the sample repository:

Notice that there are several attributes that can be specified when adding an external source:

  • classname (mandatory) - the fully qualified name of the Connector class which allows content to be retrieved and written to that external source
  • module (optional) - the name of the Wildfly module where the above class can be found
  • projections (optional) - a list of projection expressions representing predefined projection paths for the source; projections can either be defined here or programmatically using the FederationManager.createProjection(...) method.
  • queryable (optional) - a flag indicating if the content exposed from the external source should be indexed by the repository or not. By default, all content is queryable.
  • readonly (optional) - a flag indicating if only reads or both reads and writes are possible on the source
  • cacheTtlSeconds (optional) - the number of seconds any given node from the external source is to be held in the cache of the corresponding workspace
  • properties (optional) - an array of key - value pairs which allow any custom attributes to be passed down on the Connector implementation class.

To remove an external source, just invoke remove on that source:

Add dependency on other modules and deployment units

This is only available starting with ModeShape 4.6.0.Final.

When resolving configuration options which refer to external files and resources, ModeShape will use at runtime the class loader of the org.modeshape.main module. However, this class loader is isolated (cannot access) any resources which are available to another server module on which ModeShape does not explicitly depend.

In these particular cases, you can add a depends-on repository attribute which is a comma-separated list of module names which ModeShape will use in addition to its default class loader when attempting to load external files and resources.

For example, with the following configuration:

the repository externalDependenciesRepository will be able to load the files initial-content-cars.xml and cars.cnd from the deployed external-dependencies.war, when those files are packaged inside the war file under the WEB-INF/classes/config folder.

Batch mode

You can combine all these commands (except for the initial /extension=org.modeshape:add() command) into a batch operation:

Batches can be stashed or edited before they are run, and multiple commands can be easily pasted into a batch.

Clustering configuration

Starting with ModeShape 4.3 the Infinispan & JGroups configuration has changed. See this

Before configuring ModeShape to run in a cluster, make sure the JGroups subsystem is present in the Wildfly configuration.

After that, the following parts need configuring:

1) Replicated Infinispan caches for the repository store and the binary store:

2) Main repository

3) Binary Storage

4) Indexing

Migrating from ModeShape 4.2 (or lower) to ModeShape 4.3 (or greater)

Starting with 4.3, ModeShape no longer integrates with the Infinispan subsystem delivered as part of the JBoss Application Server, but rather delivers and uses Infinispan as a regular set of modules (libraries). This means that several configuration changes will be required for the ModeShape - Infinispan integration to work:

  • the ModeShape subsystem XML schema version has been changed from 2.0 to 2.1
  • any cache-container and cache elements defined for ModeShape in the Application Server's Infinispan subsystem should be removed
  • the cache-container attribute has been removed and is no longer supported for the following elements: repository, cache-binary-storage and workspaces

The Infinispan cache configurations have to be created/migrated to embedded XML files (see Configuration) and placed somewhere in the Application Server's folder structure.
By default, given a repository named X, ModeShape will look for an Infinispan configuration file under ${jboss.server.config.dir}/modeshape/X-cache-config.xml. The jboss.server.config.dir is only available in standalone mode and defaults to JBOSS_HOME/standalone/configuration.

This means that the following ModeShape 4.2 configuration:


now becomes:


and the repository configuration:


The actual location and file name of the Infinispan configuration file can be fully configured using 2 new <repository/> attributes:

  • cache-config - the relative path of the Infinispan standalone configuration file. Defaults to modeshape/repository_name-cache-config.xml.
  • config-relative-to - the folder (either via a system property or fully qualified path) where the cache-config file can be located. Defaults to ${jboss.server.config.dir}.

The optional cache-name attribute is unchanged, meaning that even if the default behavior is for ModeShape to look for an Infinspan cache with the same name as the repository, one can easily use any other named cache.

The cache-binary-storage and workspaces elements no longer support the cache-container attribute, but support the optional cache-config attribute, with the same semantics as above. The only difference is that the root folder location of the Infinispan configuration files will always be the repository's cache-relative-to attribute. If this attribute is omitted, then the default behavior is to look for Infinispan caches in the repository's cache configuration file.

If you're running in Domain mode, the jboss.server.config.dir becomes jboss.domain.config.dir and has to be explicitly defined for the config-relative-to attribute.

When clustering, in addition to the Infinispan standalone configuration file, you also have to provide a standalone JGroups configuration file, normally placed in the same location as the Infinispan configuration file:


and the repository configuration:


Note that the Infinspan configuration file refers to path of the JGroups configuration file using system properties.

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.