PublishingHubDBConnector

1 Installation

PublishingHubDBConnector 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.jpa.api.PublishingHubDBConnector:

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

3 Using PublishingHubDBConnector in an EntityModel

This requires ison entity explorer.

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

1. Select the connector instance
   Per default the instance spec is com.priint.pubserver.connector.jpa.api.PublishingHubDBConnector: (unless a custom configuration is used). The instance name is the empty string.

2. Supply the appropriate connector entity identifier
   For PublishingHubDB 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 root Bucket entity called "category".

In many older systems you will find a connector instance called "default". If not especially configured this is the same as the default instance denoted by an empty instance identifier.

4 Using PublishingHubDBConnector 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.jpa.api.PublishingHubDBConnector

Warning

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

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 "MyPubDB_2".

You must create an XML file via repository explorer in ison.

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

/com.priint.pubserver.connector.jpa.api.PublishingHubDBConnector/WerkII/default/databaseConnections.xml

The file name is arbitrary - but only one configuration file is allowed in the directory.

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>databaseConnections.xml</con:name>
    <con:type>ContentConnector</con:type>
    <con:instances>
        <con:entry key="MyPubDB_2">
            <con:PluginConfig>
                <con:custom>
                    <connectorConfig>
                        <persistenceUnitName>PublishingHubDB_2</persistenceUnitName>
                    </connectorConfig>
                </con:custom>
            </con:PluginConfig>
        </con:entry>
    </con:instances>
</con:PluginConfig>

In this special case the new instance will differ from the default in one aspect:
The database connection will be mapped to a second instance of PublishingHubDB.

For other possibilities see below.

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

com.priint.pubserver.connector.jpa.api.PublishingHubDBConnector:MyPubDB_2

Configuration Options

The connector supports the following options for its instances:

persistenceUnitName
Name of the persistence unit used. A persistence unit is bound to a database resource configured in the application server. The connector supports four difference persistence units. But only one is fully configured through the normal installation process. Per default the unit is set to PublishingHubDB. This unit is bound to the database resource named jdbc/PublishingHubDB in the application server. For more details see below.
ignoreAlreadyExistingOnPersist
Controls what happens if you try to persist data that are already existing in the database. Default: data import will fail with rollback. If ignoreAlreadyExistingOnPersist is set true then the process will step over already existing entries (ignoring their content or subordinate data).
ignoreNotExistingOnMerge
Controls what happens if you try to update data that are can not be found in the database. Default: data update will fail with rollback. If ignoreNotExistingOnMerge is set true then the process will step over non existing entries (i.e. no creation of missing items).
ignoreNotExistingOnRemove
Controls what happens if you try to remote data that are non existing in the database. Default: data removal will fail with rollback. If ignoreNotExistingOnRemove is set true then the process will step over not existing entries.

Persistence Units

A unit hash one-to-one relation to a database resource in the application server. The database resources are related to database pools. Different resources may share the same pool. The pools may use different database servers or just differ in some connection or polling properties .

The following persistence units are supported by PublishingHubDBConnector. To use units 2 to 4 you MUST manually create a resource in the application server. See appendix for the default database resource configuration. Other names than those given here are not supported.

One unit can support several entity models. There is no need to add unit just for new models.

persistenceUnitName	JDBC Resource	Preconfigured
PublishingHubDB	jdbc/PublishingHubDB	yes
PublishingHubDB_2	jdbc/PublishingHubDB_2	no
PublishingHubDB_3	jdbc/PublishingHubDB_3	no
PublishingHubDB_4	jdbc/PublishingHubDB_4	no

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, PublishingHubDBConnector uses a special JDBC resource named jdbc/PublishingHubDB. This is automatically installed by installer. The resource uses tables in the PublishingHubDB database.

The resource jdbc/PublishingHubDB is related to the PublishingHubDBPool.

PublishingHubDBPool itself points to the database priint_PublishingHubDB.

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.