MuaConnector

1 Installation

MuaConnector is part of the standard delivery of publishing server.

There is no necessity to install or update anything manually.

The appendix gives more information on the Payara and database configuration that is used by the connector.

2 Connector Configuration

Configuration of the connector is optional. The connector is functional after installation alone. Configuration is only required if you want to override the default settings of the connector. This is rarely needed.

The default connector instance string for use in ison entity editor is just an empty string. The full connector specification string for use in ison is this:

com.priint.pubserver.connector.mua.MuaConnector:

If you really need a custom configuration follow the advises in the appendix.

3 Using MuaConnector in an EntityModel

This requires ison entity explorer.

To bind an entity to MuaConnector two things must be done:

1. Select the connector instance
   Per default the instance spec is com.priint.pubserver.connector.mua.MuaConnector: (unless a custom configuration is used). The instance name is the empty string.
2. Supply the appropriate connector entity identifier.
   For mua the connector entity identifier MUST equal the identifier of the entity in the model. This must be set manually.

In the following example we created a ContentMetaData entity called "metadata1".

4 Using MuaConnector in Java Code

The connector is based on the AbstractConnector class of the API. It supports all methods supported by the abstract connector.

The mapped name of the connector is

com.priint.pubserver.connector.mua.MuaConnector

Warning

Using MuaConnector directly in Java source code is strongly discouraged for API users. Always try to use the connector via the EntityManager interface.

5 Appendix

5.1 Custom Connector Configuration

Note: Custom configurations are only needed if you want to change the default settings of the connector. Otherwise the following information can be skipped.

Suppose you want to have a custom configuration for a connector instance named "MyInstance1".

You must create a new XML file via repository explorer in ison.

If e.g. the tenant name is "WerkII" the repository location is:

/com.priint.pubserver.connector.mua.MuaConnector/WerkII/default/MyInstance1.xml

As for all connector configurations you must set the <con:name/> element and the key attribute of the <con:entry/> and some connector specific content within the <con:custom/> element.

The XML can look as follows:

<?xml version="1.0" encoding="UTF-8"?>
<con:PluginConfig xmlns:con="com.priint.pubserver.config.manager/20130620">
    <con:name>MyInstance1.xml</con:name>
    <con:type>ContentConnector</con:type>
    <con:instances>
        <con:entry key="MyInstance_1">
            <con:PluginConfig>
                <con:custom>
                    <mua-connector version="1.0">
                        <compressionThreshold>2048</compressionThreshold>
                        <serializationFormat>j</serializationFormat>
                        <jdbcResource>jdbc/MuaConnector</jdbcResource>
                        <cacheDuration>0</cacheDuration>
                    </mua-connector>
                </con:custom>
            </con:PluginConfig>
        </con:entry>
    </con:instances>
</con:PluginConfig>

Entities using this configuration need to select the following connector specification:

com.priint.pubserver.connector.mua.MuaConnector:MyInstance1

Configuration Options

The connector supports the following options for its instances:

compressionThreshold in bytes: Data as stored in serialized blobs in the database. These blobs will be compressed using gzip format if the size of the data object exceeds this threshold (in bytes). Default is 2048. Only change this if you really know what you are doing.

serializationFormat "j" or "x": Data as stored in serialized blobs in the database. Serialization format can be "j" (JSON) or "x" (XML). Default is "j" (i.e. JSON). Only change this if you really know what you are doing.

jdbcResource: Per default the connector uses "jdbc/MuaConnector" as resource name. If you want to use different data sources for different entity models you can change the value here. This requires that: (1) you create a copy of the database schema for the MUAtables in publishinghubdb in your database. But keep in mind, that the updater process of publishing server will not automatically update this new schema. (2) you configure a JDBC pool and JDBC resource for the new schema in Payara. For help please consult the payara/glassfish documentation and use the PublishingHubDBPool and jdbc/MuaConnector resource as examples (see below).

cacheDuration in seconds: The connector supports a simple query result cache. By default the cache is not activated, i.e. cacheDuration=0.You may adapt this setting to your needs. Caching is done in Java RAM.

autoFillMissingIdentifiersOnInsert "true" or "false": If during an insert operation the connector detects than an entity data item has no identifier yet, the connector will create a random identifier. Random identifiers always start with a backspace character to mark them, followed by15 random alphanumeric characters - making it 16 chars altogether. The connector will not check for collisions. In case of a collision an exception is thrown and the best remedy is to retry the call - i.e. create new random ids. Default is false.

modelIdentifier: MUA connector needs the entity model for cords to work correctly. If the configuration does not contain modelIdentifier, the connector will assume that its instance name is the same as the model identifier, as is common usage.

returnAllForEmptyContext: If this parameter is set to true, MUA connector will return all items regardless of the context if an empty string is provided for the context parameter. If set to false, the connector will return only the items with empty context if an empty string is provided for the context parameter. Default is false.

The XML example above just reiterates the default values. If you only want to change the caching setting to 2 min (120 sec) only the configuration could look like this:

<mua-connector version="1.0">
  <cacheDuration>120</cacheDuration>
</mua-connector>

5.2 Default Database Resource Configuration

Note: Custom database resource configurations are only needed in rare cases. This section informs about the default settings.

By default MuaConnector uses a special JDBC resource named jdbc/MuaConnector. This is automatically installed by installer. The resource uses tables in the PublishingHubDB database.

The resource jdbc/MuaConnector is related to MuaConnectorPool.

MuaConnectorPool itself points to the same data source as PublishingHubDBPool, i.e. the database priint\_PublishingHubDB. Actually it is a clone of PublishingHubDBPool.

The exact configuration as taken from the domain.xml is given here for a typical developer system using MySQL server on the local system. Installations for MSSQL or Oracle and installations on test or production systems will look different. Please inspect your domain.xml file. domain.xml file is located in the installation directory in sub-folder <installDir>/glassfish/payara5/glassfish/domains/pubserver/config.