CPF Plug-in Maven Project
The CPF uses maven modules for the deployment of plug-in modules to the CPF web services. Each CPF plug-in module is a maven project that contains all the code and dependencies of the plug-in. Within the CPF plug-in module one or more Business Application Classes are defined.
Create a plug-in project
The first step is to create a plug-in project. Plug-ins must be developed using Apache Maven 3.0.x.
A new plug-in project can be created using the Maven archetype mechanism. The archetype defines a template project that can be created by passing in parameters to the following command.
cd ~/projects
mvn \
archetype:generate \
-DinteractiveMode=false \
-DarchetypeGroupId=ca.bc.gov.open.cpf \
-DarchetypeArtifactId=cpf-archetype-plug-in \
-DarchetypeVersion=${project.version} \
-DgroupId=ca.bc.gov \
-DartifactId=demo \
-Dversion=1.0.0-SNAPSHOT \
-Dpackage=ca.bc.gov.demo \
-Dplug-inName=Demo \
-Dplug-inAcronym=demo
| Parameter | Description |
|---|---|
| archetypeVersion | The most recent version of the CPF framework. |
| groupId | The maven group identifier also used as the java package name for the plug-in class. For BC Government plug-ins this should be ca.bc.gov. |
| artifactId | The base maven artifact identifier used for the maven modules created in the project. This should be the project acronym for BC Government projects. |
| version | The version identifier you’d like to give to your plug-in. Must include -SNAPSHOT the -SNAPSHOT is removed on migration to test and production. |
| package | The Java package name for the generated code. Must be ca.bc.gov.{acronym} for BC Government projects. |
| pluginName | The name of the plug-in. This will be used to generate the plug-in class name and for descriptions in the Maven build files. |
| pluginAcronym | The acronym of the plug-in. This will be used to generate the plug-in jar name. |
The following directory structure would be created if the command were run using the parameters above.
| File/Directory | Description |
|---|---|
| demo/ | The root directory of the plug-in project. |
| scripts/ | Any SQL scripts required to create the database or data required by the plug-in. Samples are included. |
| README.txt | A sample readme file for deployment to the Ministry. Edit for your application. |
| pom.xml | The maven build file for the plug-in. |
| src/ | The root folder containing the source code and resources. |
| main/java/ca.bc.gov/demo/ | The java package for the plug-in, add any support classes in here. |
| DemoPlug-in.java | The java class for the plug-in. |
| main/resources/ | The non-java resource files to include in the plug-in jar. |
| META-INF/ | The META-INF directory for the plug-in jar. |
| ca.bc.gov.open.cpf.plugin.sf.xml | The main CPF spring configuration file for the plug-ins in this module. |
| ca/bc/gov/demo/Demo.sf.xml | The spring configuration file containing any beans used by the plug-ins. |
Add Dependencies
A plug-in can include dependencies to additional libraries that are not deployed as part of the core CPF application. These must be approved prior to delivering to the Ministry.
All plug-ins must either be available in the Maven central repository. Or a private repository that the CPF is configured to access.
If any of the dependencies include dependencies to logging frameworks such as LOG4J, SLF4J and especially commons-logging these must be excluded from those dependencies. This ensures that carefully controlled versions of these files are used. The CPF internally uses SLF4J as the logging API with a LOG4J binding to perform the actual logging and a bridge so that commons logging is logged via SLF4J. It is recommended for plug-ins to use SLF4J for logging in their module. Plug-ins must not include a log4j.xml file in their Jar file. A log4j.xml file can however be included in src/test/resources for testing the plug-in.
Any dependencies that are included in the CPF application itself must be marked with a scope of provided. If they are dependencies of other modules then they should be excluded from that dependency. CPF ignores any dependencies to the CPF libraries or the libraries it uses. This ensures that the correct versions of these libraries are used at runtime.
Any dependencies to test frameworks such as junit must be included using the test scope so that they are not included in the jar. Also any test code must be included below src/test as opposed to src/main.
JDBC Dependencies
The CPF supports the Oracle and PostgreSQL with PostGIS extensions JDBC drivers. The dependencies to these drivers are included through the cpf-api-plugin dependency.
*NOTE: At this time no other versions of these JDBC drivers or 3rd party JDBC drivers are supported. Any dependencies to those drivers must be excluded from the plug-in’s dependencies. Other JDBC driver versions may interfere with the running of the CPF application.
Build the plug-in
The plug-in is built using maven. Use the following command to create a clean build that is deployed to your local maven repository.
mvn clean install
The plug-in must be deployed to a maven repository so that the CPF can download the plug-in. If on a developers workstation a local maven cache can be used instead of this step.
mvn deploy
Deploy a Plug-in
Plug-ins are deployed dynamically using the CPF admin application. Follow this procedure to deploy a new module.
- Open the CPF modules admin page.
- Click the Add button on the Modules page.
- Enter the project acronym as the module name (e.g. DEMO), it will be converted to upper case.
- Enter in the maven module Id for your plug-in in the format {groupId}:{artifactId}:{version}. For example com.myapplication:demo:1.0.0-SNAPSHOT.
- Click the Save button
- The module view page will be displayed.
If the version number of a module changes, follow this procedure to update the version for an existing module.
- Open the CPF modules admin page.
- Click on the name of the module in the table, this will open the module view page.
- Click on the name of the module in the table, this will open the module view page.
- Click Edit button to edit the module.
- Enter in the maven module Id for your plug-in in the format {groupId}:{artifactId}:{version}. For example com.myapplication:demo:1.0.0-SNAPSHOT.
- Click the Save button
- The module view page will be displayed.
- Click the restart button to load the new version of the module.
NOTE: You cannot change the name of the module. Delete the existing module and create a new one.