Chapter 4. Using the Hierarchical Database with Red Hat JBoss EAP

Procedure 4.1. Task

1. Start the JBoss EAP server

   Start JBoss EAP in standalone mode with the configuration of your choice. For example, the following starts with the standalone.xml configuration file:

   $ bin/standalone.sh -c=standalone.xml

   Copy to Clipboard Toggle word wrap

2. Start the JBoss EAP Management CLI

   You can use the JBoss EAP command line interface (CLI) tool to directly manipulate the configuration of the running server. If the server is running in domain mode, the CLI immediately propagates the changes to all the servers. Start the CLI and connect to your server as shown below:

   $ ./bin/jboss-cli.sh
   You are disconnected at the moment. Type 'connect' to connect to the server or 'help' for the list of supported commands.
   [disconnected /] connect
   [standalone@localhost:9999 /]

   Copy to Clipboard Toggle word wrap

3. Add a hierarchical database subsystem

   Add the subsystem to the current configuration as shown below:

   [standalone@localhost:9999 /] /extension=org.modeshape:add()
   {"outcome" => "success"}
   [standalone@localhost:9999 /] ./subsystem=modeshape:add
   {"outcome" => "success"}

   Copy to Clipboard Toggle word wrap

   This updates the configuration's XML file (in this case standalone.xml) immediately.

4. Add a hierarchical database repository

   Before adding a repository, add or configure the JBoss EAP resources for the repository to use.

   1. Add an Infinispan cache

      Each hierarchical database repository stores its content in an Infinispan cache. The following steps show how to put this cache in a new cache container called modeshape, which you can use for other repositories:

      [standalone@localhost:9999 /] /subsystem=infinispan/cache-container=modeshape:add
      {"outcome" => "success"}

      Copy to Clipboard Toggle word wrap
      Once you have your container, here is how you can define a local cache named sample that uses non-XA transactions and persists all content immediately to the modeshape/store/sample directory under the standalone/data directory:

      						[standalone@localhost:9999 /] /subsystem=infinispan/cache-container=modeshape/local-cache=sample:add
      {"outcome" => "success"}
      [standalone@localhost:9999 /] /subsystem=infinispan/cache-container=modeshape/local-cache=sample/transaction=TRANSACTION:add(mode=NON_XA)
      {
          "outcome" => "success",
          "response-headers" => {
              "operation-requires-reload" => true,
              "process-state" => "reload-required"
          }
      }
      [standalone@localhost:9999 /] /subsystem=infinispan/cache-container=modeshape/local-cache=sample/file-store=FILE_STORE:add(path="modeshape/store/sample",relative-to="jboss.server.data.dir",passivation=false,purge=false)
      {
          "outcome" => "success",
          "response-headers" => {"process-state" => "reload-required"}
      }
      

      Copy to Clipboard Toggle word wrap
      These commands run successfully, however, the last few may require a reload of the Infinispan service. This means that your changes are saved to the configuration, but these few may not take effect until the next restart or until you explicitly perform the reload:

      [standalone@localhost:9999 /] :reload
      {
          "outcome" => "success",
          "response-headers" => {"process-state" => "reload-required"}
      }
      [standalone@localhost:9999 /] :reload
      {"outcome" => "success"}

      Copy to Clipboard Toggle word wrap

   2. Add the repository

      After defining the services for the repository to use, here is how you can define a repository called sample:

      [standalone@localhost:9999 /] ./subsystem=modeshape/repository=sample:add(security-domain="modeshape-security",cache-name="sample",cache-container="modeshape")
      {"outcome" => "success"}

      Copy to Clipboard Toggle word wrap
      This command configures the sample repository to use the sample Infinispan cache in the modeshape cache container, and to use the modeshape-security security domain created earlier. Restart is not required after defining a repository. Most of the administrative operations take effect immediately even when applications are actively using the repository.
      You need not define the security-domain="modeshape-security" attribute because the repository uses a security domain with that name by default. Also, by default the repository tries to use an Infinispan cache with the name "modeshape" which is same as the repository in the cache container. You can specify these, but any attributes that match the default value will not be serialized to the XML configuration file.

Procedure 4.2. Task

1. You can view the complete definition of a repository at any point by running the following command in the Management CLI:

   	
   [standalone@localhost:9999 /] /subsystem=modeshape/repository=sample:read-resource(recursive=true)
   {
       "outcome" => "success",
       "result" => {
           "allow-workspace-creation" => true,
           "anonymous-roles" => undefined,
           "anonymous-username" => "<anonymous>",
           "binary-storage" => undefined,
           "cache-container" => "modeshape",
           "cache-name" => "sramp",
           "cluster-name" => undefined,
           "cluster-stack" => undefined,
           "default-workspace" => "default",
           "enable-monitoring" => true,
           "index-storage" => undefined,
           "indexing-analyzer-classname" => "org.apache.lucene.analysis.standard.StandardAnalyzer",
           "indexing-analyzer-module" => undefined,
           "indexing-async-max-queue-size" => 0,
           "indexing-async-thread-pool-size" => 1,
           "indexing-batch-size" => -1,
           "indexing-mode" => "SYNC",
           "indexing-reader-strategy" => "SHARED",
           "indexing-thread-pool" => "modeshape-workers",
           "jndi-name" => undefined,
           "minimum-binary-size" => 4096,
           "predefined-workspace-names" => undefined,
           "rebuild-indexes-upon-startup" => "IF_MISSING",
           "security-domain" => "modeshape-security",
           "sequencer" => undefined,
           "use-anonymous-upon-failed-authentication" => false
       }
   }
   

   Copy to Clipboard Toggle word wrap
   This shows all the attributes including the ones that are not set, or set to their default values.
2. To view details about each attribute and child, use the :read-resource-description() command. For example:

   [standalone@localhost:9999 /] /subsystem=modeshape/repository=sample:read-resource-description(recursive=true)
   {
       "outcome" => "success",
       "result" => {
           "description" => "ModeShape repository",
           "attributes" => {
               "cache-name" => {
                   "type" => STRING,
                   "description" => "The name of the cache that is to be used for storing this repository's content",
                   "expressions-allowed" => false,
                   "nillable" => true,
                   "min-length" => 1L,
                   "max-length" => 2147483647L,
                   "access-type" => "read-write",
                   "storage" => "configuration",
                   "restart-required" => "resource-services"
               },
               "cache-container" => {
                   "type" => STRING,
                   "description" => "The name of the cache container that contains the cache to be used for storing this repository's content",
                   "expressions-allowed" => false,
                   "nillable" => true,
                   "min-length" => 1L,
                   "max-length" => 2147483647L,
                   "access-type" => "read-write",
                   "storage" => "configuration",
                   "restart-required" => "resource-services"
               },
               "jndi-name" => {
                   "type" => STRING,
                   "description" => "The optional alias in JNDI where this repository is to be registered, in addition to 'jcr/{repositoryName}",
                   "expressions-allowed" => false,
                   "nillable" => true,
                   "min-length" => 1L,
                   "max-length" => 2147483647L,
                   "access-type" => "read-write",
                   "storage" => "configuration",
                   "restart-required" => "resource-services"
               },
   ...
   

   Copy to Clipboard Toggle word wrap
   Here, the output shows the description of each attribute, the criteria for valid values, whether expressions such as system variables are allowed or not, and whether a restart is required or not before changes take effect.
   Most of the attributes have defaults, but the descriptions do not list some of the defaults 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.

Procedure 4.3. Task

1. Add a sequencer to the sample repository that operates against comma-separated value (CSV) files uploaded under the /files node as shown below:

   [standalone@localhost:9999 /] /subsystem=modeshape/repository=sample/sequencer=delimited-text-sequencer:add( classname="org.modeshape.sequencer.text.DelimitedTextSequencer", module="org.modeshape.sequencer.text", path-expressions=["/files(//*.csv[*])/jcr:content[@jcr:data] => /derived/text/delimited/$1"], properties=[{ "splitPattern"=>"," }])
   {"outcome" => "success"}
   [standalone@localhost:9999 /] /subsystem=modeshape/repository=sample/sequencer=delimited-text-sequencer:read-resource()
   {
       "outcome" => "success",
       "result" => {
           "classname" => "org.modeshape.sequencer.text.DelimitedTextSequencer",
           "module" => "org.modeshape.sequencer.text",
           "path-expressions" => ["/files(//*.csv[*])/jcr:content[@jcr:data] => /derived/text/delimited/$1"],
           "properties" => [{"splitPattern" => ","}]
       }
   }

   Copy to Clipboard Toggle word wrap

   This sequencer has an additional splitPattern property that specifies the delimiter.
2. To remove a sequencer, invoke the remove operation on the appropriate item as shown below:

   [standalone@localhost:9999 /] /subsystem=modeshape/repository=sample/sequencer=delimited-text-sequencer:remove()
   {"outcome" => "success"}

   Copy to Clipboard Toggle word wrap

Procedure 4.4. Task

1. To specify where indexes are stored, add the index storage resource to your configuration as shown below:

   [standalone@localhost:9999 /] /subsystem=modeshape/repository=sample/configuration=index-storage:add()   
   {"outcome" => "success"}

   Copy to Clipboard Toggle word wrap
2. Once you add the index storage node, add the storage type with required optional parameters as shown below:

   [standalone@localhost:9999 /] /subsystem=modeshape/repository=sample/configuration=index-storage/storage-type=master-file-index-storage:add(connection-factory-jndi-name=conn-name,queue-jndi-name=queue-name, path=/somepath, source-path=/someotherpath)                                       
   {"outcome" => "success"}

   Copy to Clipboard Toggle word wrap

Procedure 4.5. Task

1. To specify where large binary values are stored, you need to first add the binary storage resource to your configuration as shown below:

   [standalone@localhost:9999 /] /subsystem=modeshape/repository=sample/configuration=binary-storage:add()   
   {"outcome" => "success"}

   Copy to Clipboard Toggle word wrap
2. Once you add the binary storage node, add the storage type with the required optional parameters as shown below:

   [standalone@localhost:9999 /] /subsystem=modeshape/repository=sample/configuration=binary-storage/storage-type=file-binary-storage:add(path=/somepath)
   {"outcome" => "success"}

   Copy to Clipboard Toggle word wrap

Procedure 4.6. Task

1. Configure composite binary stores via CLI as shown below:

   [standalone@localhost:9999 /] /subsystem=modeshape/repository=sample/configuration=binary-storage/storage-type=composite-binary-storage:add()

   Copy to Clipboard Toggle word wrap
   Ensure that each nested store has a store-name property that 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
2. Add a file system binary store to a composite store as shown below:

   [standalone@localhost:9999 /] /subsystem=modeshape/repository=sample/configuration=binary-storage/storage-type=composite-binary-storage/nested-storage-type-file=filesystem1:add(store-name=filesystem1, path="/somepath")

   Copy to Clipboard Toggle word wrap
   You can remove a file system binary store from a composite store as shown below:

   [standalone@localhost:9999 /] /subsystem=modeshape/repository=sample/configuration=binary-storage/storage-type=composite-binary-storage/nested-storage-type-file=filesystem1:remove()

   Copy to Clipboard Toggle word wrap

Procedure 4.7. Task

1. If your org.modeshape.jcr.security.AuthorizationProvider implementation is named org.example.MyAuthProvider and is added to a new org.example.auth module, then use the following command to add this provider to the "sample" repository:

   [standalone@localhost:9999 /] /subsystem=modeshape/repository=sample/authenticator=custom:add(classname="org.example.MyAuthProvider", module="org.example.auth")
   {"outcome" => "success"}
   [standalone@localhost:9999 /] /subsystem=modeshape/repository=sample/authenticator=jaas:read-resource()
   {
       "outcome" => "success",
       "result" => {
           "classname" => "org.modeshape.jcr.security.JaasProvider",
           "module" => "org.modeshape",
           "properties" => undefined
       }
   }

   Copy to Clipboard Toggle word wrap
2. To remove an authentication provider, invoke the "remove" operation on the appropriate item as shown below:

   [standalone@localhost:9999 /] /subsystem=modeshape/repository=sample/authenticator=custom:remove()
   {"outcome" => "success"}
   

   Copy to Clipboard Toggle word wrap

Procedure 4.8. Task

• You can set the auth-domain field on the MyAuthProvider instance to the String value "global". To do this, add them via the properties parameter, which is a list of documents that each contain a single name-value pair:

  [standalone@localhost:9999 /] /subsystem=modeshape/repository=sample/authenticator=custom:add(classname="org.example.MyAuthProvider", module="org.example.auth", properties=[ {"foo"=>"bar"}, {"baz"=>"bam"} ] )
  {"outcome" => "success"}
  /subsystem=modeshape/repository=sample/authenticator=custom:read-resource()
  {
      "outcome" => "success",
      "result" => {
          "classname" => "org.example.MyAuthProvider",
          "module" => "org.example.auth",
          "properties" => [
              {"foo" => "bar"},
              {"baz" => "bam"}
          ]
      }
  }

  Copy to Clipboard Toggle word wrap

Procedure 4.9. Task

• Add the JDBC Data Source as shown below:

  [standalone@localhost:9999 /] /subsystem=datasources/data-source="java:/datasources/ModeShapeDS":add(jndi-name="java:/datasources/ModeShapeDS",driver-name="modeshape-driver",connection-url="jdbc:jcr:jndi:jcr?repositoryName=artifacts",user-name="admin",password="admin")
  {"outcome" => "success"}

  Copy to Clipboard Toggle word wrap

Procedure 4.10. Task

1. You can add one or more external sources to an existing repository to enable federation. Here is an example on how you can link an external file system source(via the FileSytemConnector) to the sample repository using the CLI:

   [standalone@localhost:9999 /] /subsystem=modeshape/repository=sample/source=fsSource:add(classname="org.modeshape.connector.filesystem.FileSystemConnector",properties=[{"directoryPath"=>"."}], readonly="true",
    projections=["default:/projection1 => /"], cacheTtlSeconds="1")
   {"outcome" => "success"}
    
   [standalone@localhost:9999 /] /subsystem=modeshape/repository=sample/source=fsSource:read-resource()
   {
       "outcome" => "success",
       "result" => {
           "cacheTtlSeconds" => "1",
           "classname" => "org.modeshape.connector.filesystem.FileSystemConnector",
           "module" => undefined,
           "projections" => ["default:/projection1 => /"],
           "properties" => [{"directoryPath" => "."}],
           "queryable" => undefined,
           "readonly" => "true"
       }
   }
   

   Copy to Clipboard Toggle word wrap
2. Specify the following attributes when adding an external source:
   • classname (mandatory) - The fully qualified name of the Connector class that allows content to be retrieved and written to that external source.
   • module (optional) - The name of the JBoss EAP module where the above class is 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, this flag is set.
   • readonly (optional) - A flag indicating if only read or both read and write is possible on the source.
   • cacheTtlSeconds (optional) - The number of seconds any given node is to be held in the cache of the corresponding workspace from the external source.
   • properties (optional) - An array of key-value pairs that allow any custom attributes to be passed down on the Connector implementation class.
3. To remove an external source, invoke the remove method on the source as shown below:

   [standalone@localhost:9999 /] /subsystem=modeshape/repository=sample/source=fsSource:remove()
   {"outcome" => "success"}

   Copy to Clipboard Toggle word wrap

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

   /subsystem=infinispan/cache-container=modeshape:add(module="org.modeshape")
   /subsystem=infinispan/cache-container=modeshape/transport=TRANSPORT:add(lock-timeout="60000")
   /subsystem=infinispan/cache-container=modeshape/replicated-cache=sample:add(mode="SYNC", batching="true")
   /subsystem=infinispan/cache-container=modeshape/replicated-cache=sample/transaction=TRANSACTION:add(mode=NON_XA)
   /subsystem=infinispan/cache-container=modeshape/replicated-cache=sample/file-store=FILE_STORE:add(path="modeshape/store/sample-${jboss.node.name}",relative-to="jboss.server.data.dir",passivation=false,purge=false)
   /subsystem=infinispan/cache-container=modeshape-binary-store:add(module="org.modeshape")
   /subsystem=infinispan/cache-container=modeshape-binary-store/transport=TRANSPORT:add(lock-timeout="60000")
   /subsystem=infinispan/cache-container=modeshape-binary-store/replicated-cache=sample-binary-data:add(mode="SYNC", batching="true")
   /subsystem=infinispan/cache-container=modeshape-binary-store/replicated-cache=sample-binary-data/transaction=TRANSACTION:add(mode=NON_XA)
   /subsystem=infinispan/cache-container=modeshape-binary-store/replicated-cache=sample-binary-data/file-store=FILE_STORE:add(path="modeshape/binary-store/sample-data-${jboss.node.name}",relative-to="jboss.server.data.dir",passivation=false,purge=false)
   /subsystem=infinispan/cache-container=modeshape-binary-store/replicated-cache=sample-binary-metadata:add(mode="SYNC", batching="true")
   /subsystem=infinispan/cache-container=modeshape-binary-store/replicated-cache=sample-binary-metadata/transaction=TRANSACTION:add(mode=NON_XA)
   /subsystem=infinispan/cache-container=modeshape-binary-store/replicated-cache=sample-binary-metadata/file-store=FILE_STORE:add(path="modeshape/binary-store/sample-metadata-${jboss.node.name}",relative-to="jboss.server.data.dir",passivation=false,purge=false)

   Copy to Clipboard Toggle word wrap
2. The main repository:

   /subsystem=modeshape/repository=sample:add(cache-container="modeshape",cache-name="sample",cluster-name="modeshape-sample",cluster-stack="tcp",security-domain="modeshape-security")

   Copy to Clipboard Toggle word wrap
3. Indexing:

   /subsystem=modeshape/repository=sample/configuration=index-storage:add()
   /subsystem=modeshape/repository=sample/configuration=index-storage/storage-type=local-file-index-storage:add(path="modeshape/indexes/sample-indexes-${jboss.node.name}")

   Copy to Clipboard Toggle word wrap
4. Binary Storage:

   /subsystem=modeshape/repository=sample/configuration=binary-storage:add()
   /subsystem=modeshape/repository=sample/configuration=binary-storage/storage-type=cache-binary-storage:add(data-cache-name="sample-binary-data", metadata-cache-name="sample-binary-metadata", cache-container="modeshape-binary-store")

   Copy to Clipboard Toggle word wrap