You are viewing the documentation for Blueriq 14. Documentation for other versions is available in our documentation directory.
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 groupId
, artifactId
, version
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
- Start Spring Tool Suite (STS)/Eclipse
- Select/switch your workspace folder.
- Right click in the Package Explorer, click import
- Under Maven select Existing Maven Projects
- Select as root directory the project folder (Target folder in Project Builder)
- You should see the one project with checkbox, like:
- /pom.xml - com.example:my-blueriq-application:1.0-SNAPSHOT:war
- Click Finish
- 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:
@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:
<?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.
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:
@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
- Configure database drivers: Configuring JDBC database drivers
- Deploy the WAR to your application server: Installing Java Runtime
3 Comments
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.
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"
Tom Schut
maybe revisit this path