These tools provide functionality that either is not delivered otherwise (consistency checking, statistics) or must be available without a running engine (low-level content browser).
The support tools in the stricter sense are deployed on the engine as SDA. They connect to the database in the same way as the offline configuration editor. Even though the engine does not have to be running for the tools to work, an Engine installation is required for this scenario.
Note that in the Engine scenario, the tool is not started directly as main class, but instead a "Offline tool starter" class is used which gets as a parameter the class name of the class to start and a directory with jars. The tool starter provides a special class loader from which a Datasource can be obtained reflectively. JDBC drivers are not part of this SDA, but are taken from the engine installation.
It is also possible to run the support tools in a self-contained "standalone" mode. In that case, database connection information has to be provided manually in order to create a JDBC connection to the database (see below). The JDBC drivers are packed into this distribution. Since there are license issues with these drivers, this distribution is only to be used internally.
All support tools should extend from this class, as it offers convenience and scenario independence, in particular for obtaining the database connection and configuring the PCD.
In the Engine scenario, the database connection is obtained in the same way as with the offline configuration manager. It is not possible to connect to a database other than the database of the Engine onto which the tools were deployed.
The logic to obtain a DataSource is encapsulated in OfflineDatasourceProxy (from the standalone_init project).
In the standalone scenario, instead of working with properties files, the database connection is created interactively. This avoids cumbersome editing of properties files and allows the user to enter the required login information on a screen instead.
With OpenSQL datasources, initialization is always done using JDBC driver name, JDBC URL, Username and password. While the JDBC URL looks different for each database implementation, it always can be generated from the database host name (or IP address), the port number, and the database (or schema) name.
The following databases are supporetd: Microsoft SQL Server, Oracle, DB6, and SAP Database (MaxDB).
In the Engine case, the InitDialog is initialized using the file <j2ee>/configtool/config.properties. This always has a property "rdbms.driverLocation". In case this property is found, the InitDialog assumes that it is running in "Engine" mode and if set to visible does not show the connection dialog, but connects to the database invisibly in the background: the datasource is obtained from the OfflineDatasourceProxy, the pool factory is initialized using the Datasource, and the PlFactory is initialized using this pool factory and the standalone proxies for locking and transactions.
The user first has to select which of the supported databases they use. On the connection dialog, they have to set database name, host, port number, user and password. Then they click "generate JDBC URL" and finally "connect".
From the database implementation selected in the first step, the JDBC driver name and the logic of the JDBC URL generation is known.
In the standalone case, there is one dbDriver.properties file per database type (found in the file system under /dbDrivers/<dbtype>/). This contains the JDBC driver name and a URL template as well as a default host ("localhost") and a default port (db-type dependent). The corresponding fields in the init dialog are filled with the default values (if they have not been overwritten by the user yet). The user accepts or overwrites these fields, and upon "generate URL", the placeholders in the URL template are replaced with the actual values. Upon "save", the overwritten values are stored in file "config.properties" next to the dbDriver.properties. Upon "load" the stored properties are read from that file.
Upon "connect", the driver name, generated url, user, and password are used to initialize the pool factory and then the PlFactory using this pool factory and the standalone proxies for locking and transactions.
In the standalone scenario, the pcd configuration can be changed by adding values to the pcdStartup.properties file (not extensively tested). The logic is in the initialization class. Similar logic is currently not implemented in the engine scenario, but could easily be adapted.
AbstractAdminTool provides one initialziation method with two String parameters. The first String is the path to the file containing the configuration properties (either the offline config editor configuration in the engine scenario or the local properties file in the standalone scenario), the second parameter the file path to the pcdStartup.properties (which may be empty unless special configuration should be used). Internally, this initializes an instance of the PcdHandler (see below).
Concrete subclasses of the AbstractAdminTool class must first call super.init(String, String). Afterwards, they must call getInitDialog.setVisible(true) in order to actually initialize the PCD. After that, the PlFactory is initialized, so subsequent calls to PlFactory.getInstance() result in a valid object from which the database connection can be obtained.
The initial PCD context can be obtained by a call to
IPcdContext root = Init.getInstance().getInitialPcdContext();
Note that the PCD initialization is done lazily (upon the first call to Init.getInitialPcdContext()) in order to allow running the tool against the database only (even if the PCD initialization results in Exception due to inconsistencies or such). This means that other methods to obtain the PCD initial context won't work, for example new InitialContext() or such.
The respective assemble projects contain suitable batch/shell scripts to start the different tools. Adding a new tool should be as simple as adding a new shell script with the new main class to use.