You are viewing the documentation for Blueriq 16. Documentation for other versions is available in our documentation directory.

When you want to develop custom plugins for your project, you need to create your own WAR that contains both the Blueriq functionality and your custom plugins. This page describes how you can accomplish this.

Prerequisites

  • You need a (current) Blueriq release

  • You need to have a connection to the Blueriq Artifactory. If you do not have this yet, see Setting up connection to Blueriq Artifactory.

  • You need SpringSource Tool Suite (Recommend) OR Eclipse IDE (for Java EE Developers) with the M2Eclipse plugin
    Note: Maven and the M2Eclipse plugin are already installed with SpringSource Tool Suite

On this page:


Create a Blueriq Java Runtime project

To create a new Blueriq Java Runtime project, you can use the projectstarter zips that are delivered with a Blueriq release. A projectstarter zip contains the files needed to create a Maven project that generates a WAR for a specific application server. A release contains projectstarter zips for each supported application server. For the supported application servers refer to the Platform support Blueriq.

You can find the projectstarter zips in the release zip in the folder \Deploy\Runtime\Development. Pick the projectstarter zip for the application server you are going to deploy to and expand the contents in a folder of your choice (since Blueriq 11 only JBoss-EAP 6.4 has a separated project starter. other supported application servers can use the default blueriq-runtime-application-starter).

Projectstarter contents

When you have expanded the projectstarter zip in a folder, you will find the following:

  • pom.xml
  • resources (src/main/resources)
  • application server specific configuration (src/main/webapp)

pom.xml

The pom.xml contains the information to build the custom WAR. Change the groupIdartifactIdversion and name to match your project conventions. You also need to change the com.blueriq.version property to the Blueriq version that you are going to use, preferably the latest release available. You can then add your custom plugins as dependencies to add them to the WAR.

Blueriq dependencies

The pom.xml imports the Blueriq parent for the application server as 'Bill Of Materials' and includes it as a regular dependency. This ensures that all the libraries required to run Blueriq on the application server are added to the WAR.

Blueriq plugins

The optional Blueriq plugins are also in the pom.xml, commented out. If you want to use a plugin, simply uncomment the dependency and it will be added to the WAR, including its dependencies.

Resources

The resources folder (src/main/resources) contains the default bootstrap and logging configuration. You can either change these to make the WAR contain your changes, or you can choose to override specific settings from the 

spring.config.additional-location
.

Application server specific resources

The application server specific resources (src/main/webapp) contain application server specific configuration, for example a jboss-web.xml for JBoss. These resources are included in the WAR as well.

Create Custom Plugin

  1. Start Spring Tool Suite (STS)/Eclipse
  2. Select/switch your workspace folder.
  3. Right click in the Package Explorer, click import
  4. Under Maven select Existing Maven Projects
  5. Select as root directory the project folder (Target folder in Project Builder)
  6. You should see the one project with checkbox, like:
    • /pom.xml - com.example:my-blueriq-application:1.0-SNAPSHOT:war
  7. Click Finish
  8. In the root pom.xml, update the <com.blueriq.version> to the appropriate version.

Project structure

  • my-blueriq-tomcat-project This is the main project where you could create your custom blueriq extension (Services, Containers, etc), or you can create a separate maven module and add it as a dependency to this project.

Note: “my-blueriq-tomcat-project” is an example name

Configuration Class

When creating a plugin in a separate module, a configuration class needs to added to the module. In the class specific annotations are required for Blueriq to scan the packages. An example is displayed below:

com.example.plugin.config.CustomConfig.java
@Configuration
@ComponentScan(basePackages = { "com.example.plugin.feature" })
public class CustomConfig {
  //Custom beans
}


There are 2 ways that a custom plugin will be picked up by the Runtime. You can choose either one but not together.

XML config

The component scanning can also be configured in a configuration file, named 'aquima-plugin-context.xml'  and placed in the resources folder (src/main/resources). An example is displayed below:

src/main/resources/aquima-plugin-context.xml
<?xml version="1.0" encoding="UTF-8"?> 
<beans xmlns="http://www.springframework.org/schema/beans" 
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:context="http://www.springframework.org/schema/context" 
	xsi:schemaLocation=" 
		http://www.springframework.org/schema/beans 
		http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
		http://www.springframework.org/schema/context 
		http://www.springframework.org/schema/context/spring-context-3.0.xsd"> 
 
	<context:component-scan base-package="com.example.plugin.config" /> 
 
</beans> 


WarApplication

In the projectstarter you'll find a class called WarApplication.java. In this file you can add your CustomConfig to the RootConfig.

WarApplication.java
import com.example.plugin.config.CustomConfig;
import com.aquima.web.boot.RootConfig;

public class WarApplication extends AbstractWarApplication {

  @Override
  protected SpringApplicationBuilder configure(SpringApplicationBuilder application) {
	// first initialize the Blueriq configuration, than load your custom configuration
    return RootConfig.configure(application).sources(CustomConfig.class);
  }  
}

Persistence before Blueriq 11.5

For data persistence the plugins can configure their own datasource, session factory and transaction manager. An example is displayed below:

com.example.plugin.data.MyPluginExternalConfig
@Configuration
@EnableTransactionManagement
@Profile(DataSourceProfile.EXTERNAL_DATASOURCE_PROFILE_NAME)
public class MyPluginExternalConfig {

  @Autowired
  private ConfigurableEnvironment configurableEnv;

  @Autowired
  private IBlueriqDataSourceBuilder dataSourceBuilder;
  
  public static final String DATA_SOURCE_NAME = "myPluginDataSource";
  public static final String ENTITY_BASE_PACKAGE = "com.example.plugin.model";
  public static final String SESSION_FACTORY_NAME = "myPluginSessionFactory";
  public static final String TRANSACTION_MANAGER_NAME = "myPluginTransactionManager";
  public static final String PLUGIN_DATASOURCE = "myPluginData";

  @Bean(name = TRANSACTION_MANAGER_NAME)
  public HibernateTransactionManager myPluginTransactionManager(
      @Qualifier(SESSION_FACTORY_NAME) SessionFactory sessionFactory) {
    return new HibernateTransactionManager(sessionFactory);
  }

  @RefreshScope
  @Bean(name = SESSION_FACTORY_NAME)
  public LocalSessionFactoryBean myPluginSessionFactory(
      @Qualifier(DATA_SOURCE_NAME) DataSource dataSource) {
    LocalSessionFactoryBean sessionFactory = new LocalSessionFactoryBean();
    sessionFactory.setDataSource(dataSource);
    sessionFactory.setPackagesToScan(ENTITY_BASE_PACKAGE);
    sessionFactory.setHibernateProperties(
        DatasourcePropertiesUtil.getHibernateProperties(configurableEnv, PLUGIN_DATASOURCE));
    return sessionFactory;
  }

  @RefreshScope
  @Bean(name = DATA_SOURCE_NAME)
  public DataSource myPluginDataSource() {
    return dataSourceBuilder.buildDataSource(PLUGIN_DATASOURCE);
  }
}

Persistence since Blueriq 11.5

For data persistence the plugins can configure their own datasource, session factory and transaction manager. https://github.com/blueriq/blueriq-example-custom-database-component

Build the WAR

You can build the WAR with Maven:

$ mvn clean verify

Further steps


2 Comments

  1. Unknown User (m.finnerud)

    "A release contains projectstarter zips for each supported application server. For the supported application servers refer to the Platform support Blueriq 10." 

    Link to Platform support Blueriq 10 refers to a deleted page and it looks like there is only a projectstarter zip for JBoss.

    1. Unknown User (r.de.haard)

      I fixed the link and updated the description. Since Blueriq 11 only JBoss-EAP-6.4 has a separated projectstarter all other supported application servers can use the default "blueriq-runtime-application-starter"