11 Building Oracle Coherence Projects with Maven

You can use the Oracle Coherence archetypes to create, build, and deploy Oracle Coherence applications.

Topics:

• Introduction to Building Oracle Coherence Projects with Maven
  Oracle Fusion Middleware provides a Maven plug-in and an archetype is provided for Oracle Coherence Grid Archive (GAR) projects.
• Creating a Coherence Project from a Maven Archetype
  You can create a new Coherence project using the Coherence Maven archetype.
• Building Your Coherence Project with Maven
  After you have written your project code, you can use Maven to build the project:
• Deploying Your Coherence Project to the WebLogic Server Coherence Container with Maven
  To deploy your GAR to a Coherence Container in a WebLogic Server environment, you must add some additional configuration to your project's POM file.
• Building a More Complete Coherence Example
  In a real application, you are likely to have not just a GAR project, but also some kind of client project that interacts with the Coherence cache established by the GAR.

Introduction to Building Oracle Coherence Projects with Maven

Oracle Fusion Middleware provides a Maven plug-in and an archetype is provided for Oracle Coherence Grid Archive (GAR) projects.

Table 11-1 describes the Maven coordinates.

Table 11-1 Maven Coordinates with Coherence

artifacts	groupId	artifactId	version
GAR Plugin	com.oracle.coherence	gar-maven-plugin	12.2.1-0-0
GAR Archetype	com.oracle.coherence.archetype	gar-maven-archetype	12.2.1-0-0

Table 11-2 describes the goals supported by the Oracle Coherence plug-in.

Table 11-2 Oracle Coherence Goals

Goal	Purpose
generate-descriptor	Generates the project's POF configuration file.
package	Packages the basic GAR assets, including library dependencies into a JAR archive.
repackage	Repackages the packaged JAR archive with optional metadata and GAR extension.

Creating a Coherence Project from a Maven Archetype

You can create a new Coherence project using the Coherence Maven archetype.

1. To create a new Coherence project using the Coherence Maven archetype, run a command similar to the following:

   mvn archetype:generate
       -DarchetypeGroupId=com.oracle.coherence.archetype
       -DarchetypeArtifactId=gar-maven-archetype
       -DarchetypeVersion=12.2.1-0-0
       -DgroupId=org.mycompany
       -DartifactId=my-gar-project
       -Dversion=1.0-SNAPSHOT
   

   This command runs Maven's archetype:generate goal which lets you create a new project from an archetype. Table 11-3 describes the parameters.

   Table 11-3 Parameters for the Coherence Projects

   Parameter	Purpose
   archetypeGroupId	The group ID of the archetype that you want to use to create the new project. This must be com.oracle.coherence.archetype.
   archetypeArtifactId	The artifact ID of the archetype that you want to use to create the new project. This must be gar-maven-archetype.
   archetypeVersion	The version of the archetype that you want to use to create the new project. This must be 12.2.1-0-0.
   groupId	The group ID for your new project. This usually starts with your organization's domain name in reverse format.
   artifactId	The artifact ID for your new project. This is usually an identifier for this project.
   version	The version for your new project. This is usually 1.0-SNAPSHOT for a new project.

   You can also run the command without any arguments, as shown in the following example. In this case, Maven displays a list of available archetypes and prompts you to enter the required information.

   mvn archetype:generate

   After you create the project, the following files get included in it:

   Figure 11-1 Maven Project Files

   
   Description of "Figure 11-1 Maven Project Files"

   Table 11-4 describes the files included in the project.

   Table 11-4 Files Created for the Coherence Project

   File	Purpose
   pom.xml	The Maven Project Object Model (POM) file that describes your new project. It includes the Maven coordinates that you specified for your project and the appropriate plug-in definitions to use the Coherence Maven plug-in to build your project into a gar file.
   cache-config.xml	A starter Coherence cache configuration file.
   coherence-application.xml	A starter Coherence GAR deployment descriptor for your GAR file.
   pof-config.xml	A starter Coherence Portable Object Format (POF) configuration file. The POF configuration file is processed and inserted into the final GAR file if the plug-in option generatePof is set to true. By default, POF configuration metadata will not be generated.

   Here are the samples of the generated files listed in the above table:

   pom.xml

   <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
            xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
     <groupId>org.mycompany</groupId>
     <artifactId>my-gar-project2</artifactId>
     <version>1.0-SNAPSHOT</version>
     <packaging>gar</packaging>
     <dependencies>
       <dependency>
         <groupId>com.oracle.coherence</groupId>
         <artifactId>coherence</artifactId>
         <version>[12.2.1-3,12.2.1-4)</version>
         <scope>provided</scope>
       </dependency>
     </dependencies>
     <build>
       <plugins>
         <plugin>
           <groupId>com.oracle.coherence</groupId>
           <artifactId>gar-maven-plugin</artifactId>
           <version>12.2.1-3-23</version>
           <extensions>true</extensions>
         </plugin>
         <plugin>
           <groupId>org.apache.maven.plugins</groupId>
           <artifactId>maven-jar-plugin</artifactId>
           <version>2.6</version>
           <configuration>
             <forceCreation>true</forceCreation>
           </configuration>
         </plugin>
       </plugins>
     </build>
   </project>

   cache-config.xml

   <?xml version="1.0"?>
   
   <!--
   This XML document is a default Coherence Cache Configuration deployment descriptor that should be
   customized (or replaced) for your particular caching and deployment requirements.
   
   This configuration is usable in servers, proxies, clustered clients, and non-clustered extend clients.
   
   When used from within a server such a DefaultCacheServer, the server will automatically host a storage enabled cache
   service as well as a proxy service to allow extend clients to access the caches.  Clients using the configuration are
   storage disabled by default.
   
   This configuration defines a number of inter-related cache schemes:
   
    - server      - this scheme defines the storage tier for all caches
    - thin-direct - this scheme is for use by cluster members to access the caches hosted by the "server" scheme
    - near-direct - this scheme adds near caching to "thin-direct"
    - thin-remote - conceptually similar to "thin-direct" but for use by extend clients
    - near-remote - conceptually similar to "near-direct" but for use by extend clients
   
   The default scheme for caches is "near-direct".  This default can be overridden via two system properties.  The
   "coherence.profile" system property controls the first portion of the scheme name and defines the approach used for
   in-process caching, i.e. "near" (on-demand) or "thin" (none).  The "coherence.client" system property controls how a
   client connects to the cluster, i.e. "direct" (cluster member) or "remote" (extend client).
   
   Note: System properties defined within this cache configuration are specific to this configuration and are not
   meaningful to other cache configurations unless similarly defined there.
   -->
   <cache-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xmlns="http://xmlns.oracle.com/coherence/coherence-cache-config"
                 xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config coherence-cache-config.xsd">
     <caching-scheme-mapping>
       <cache-mapping>
         <cache-name>*</cache-name>
         <scheme-name>${coherence.profile near}-${coherence.client direct}</scheme-name>
       </cache-mapping>
     </caching-scheme-mapping>
   
     <caching-schemes>
       <!-- near caching scheme for clustered clients -->
       <near-scheme>
         <scheme-name>near-direct</scheme-name>
         <front-scheme>
           <local-scheme>
             <high-units>{front-limit-entries 10000}</high-units>
           </local-scheme>
         </front-scheme>
         <back-scheme>
           <distributed-scheme>
             <scheme-ref>thin-direct</scheme-ref>
           </distributed-scheme>
         </back-scheme>
       </near-scheme>
   
       <!-- near caching scheme for extend clients -->
       <near-scheme>
         <scheme-name>near-remote</scheme-name>
         <scheme-ref>near-direct</scheme-ref>
         <back-scheme>
           <remote-cache-scheme>
             <scheme-ref>thin-remote</scheme-ref>
           </remote-cache-scheme>
         </back-scheme>
       </near-scheme>
   
       <!-- remote caching scheme for accessing the proxy from extend clients -->
       <remote-cache-scheme>
         <scheme-name>thin-remote</scheme-name>
         <service-name>RemoteCache</service-name>
         <proxy-service-name>Proxy</proxy-service-name>
       </remote-cache-scheme>
   
       <!-- partitioned caching scheme for clustered clients -->
       <distributed-scheme>
         <scheme-name>thin-direct</scheme-name>
         <scheme-ref>server</scheme-ref>
         <local-storage system-property="coherence.distributed.localstorage">false</local-storage>
         <autostart>false</autostart>
       </distributed-scheme>
   
       <!-- partitioned caching scheme for servers -->
       <distributed-scheme>
         <scheme-name>server</scheme-name>
         <service-name>PartitionedCache</service-name>
         <local-storage system-property="coherence.distributed.localstorage">true</local-storage>
         <backing-map-scheme>
           <local-scheme>
             <high-units>{back-limit-bytes 0B}</high-units>
           </local-scheme>
         </backing-map-scheme>
         <autostart>true</autostart>
       </distributed-scheme>
   
       <!-- proxy scheme that allows extend clients to connect to the cluster over TCP/IP -->
       <proxy-scheme>
         <service-name>Proxy</service-name>
         <autostart>true</autostart>
       </proxy-scheme>
     </caching-schemes>
   </cache-config>

   coherence-application.xml

   <?xml version="1.0" encoding="ISO-8859-1"?>
   <coherence-application xmlns="http://xmlns.oracle.com/weblogic/coherence-application">
     <cache-configuration-ref>META-INF/cache-config.xml</cache-configuration-ref>
     <pof-configuration-ref>META-INF/pof-config.xml</pof-configuration-ref>
   </coherence-application>

   pof-config.xml

   <?xml version="1.0"?>
   <!-- Note: To add custom types, create a new 'pof-config.xml' file
        containing your custom user-type elements, and place it at the
        beginning of the class path. -->    
   
   <pof-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xmlns="http://xmlns.oracle.com/coherence/coherence-pof-config"
                 xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-pof-config coherence-pof-config.xsd">        
     <user-type-list>
       <!-- by default just include coherence POF user types -->
       <include>coherence-pof-config.xml</include>    
     </user-type-list>
   </pof-config>

2. If you are using POF in your project, you must add the following parameter into your project's POM file:

   Parameter	Purpose
   generatePof	The POF configuration file is generated and inserted into the final GAR file if this plug-in option is true. The configuration file is generated by scanning all classes in the GAR's classpath annotated with the class com.tangosol.io.pof.annotation.Portable. By default, POF configuration metadata is not generated.

3. To generate a GAR with correctly generated pof-config.xml, add the following to your GAR plug-in configuration in the POM:

   <build>
   <plugins>
   …
       <plugin>
         <groupId>com.oracle.coherence</groupId>
         <artifactId>gar-maven-plugin</artifactId>
         <version>12.2.1-0-0</version>
         <extensions>true</extensions>
         <configuration>
            <generatePof>true</generatePof>
         </configuration>
       </plugin>
   …
     </plugins>
   </build>

Building Your Coherence Project with Maven

After you have written your project code, you can use Maven to build the project:

1. To compile the source code in your project, execute the following command:

   mvn compile
   

2. To package the compiled source into a GAR, execute the following command. Note that this command runs all steps up to package, including the compile.

   mvn package

Deploying Your Coherence Project to the WebLogic Server Coherence Container with Maven

To deploy your GAR to a Coherence Container in a WebLogic Server environment, you must add some additional configuration to your project's POM file.

Take these steps:

1. Add instructions to use the Oracle WebLogic Maven plug-in to deploy the GAR, as shown in the following example:

             <plugin>
               <groupId>com.oracle.weblogic</groupId>
               <artifactId>weblogic-maven-plugin</artifactId>
               <version>12.2.1-0-0</version>
               <executions>
                 <!--Deploy the application to the server-->
                 <execution>
                   <phase>pre-integration-test</phase>
                   <goals>
                     <goal>deploy</goal>
                   </goals>
                   <configuration>
                     <adminurl>t3://localhost:7001</adminurl>
                     <user>weblogic</user>
                     <password>'password'</password>
                     <!--The location of the file or directory to be deployed-->
                     <source>${project.build.directory}/${project.build.finalName}.${project.packaging}</source>
                     <!--The target servers where the application is deployed-->
                     <targets>AdminServer</targets>
                     <verbose>true</verbose>
                     <name>${project.build.finalName}</name>
                   </configuration>
                 </execution>
               </executions>
             </plugin>
   

2. After you have added this section to your POM, use the following command to compile, package, and deploy your GAR to the WebLogic Server:

   mvn verify

Building a More Complete Coherence Example

In a real application, you are likely to have not just a GAR project, but also some kind of client project that interacts with the Coherence cache established by the GAR.

Refer to Building a Real Application with Maven to see an example that includes a Coherence GAR and a web application (WAR) that interacts with it.