Introducing the Oracle APEX Maven plugin

I’m currently in the process of building a Maven plugin to make APEX development even more fun and productive. The primary goal of the Oracle APEX Maven plugin is to streamline and facilitate the build process for APEX applications. That might sound a bit confusing for those of you who are not familiar with Maven or any other build management tool, so let me explain some of the terms I have used so far.

Build process: The steps required to construct something that has an observable and tangible result. A process is typically characterized by its ability to be automated. In other words, when we talk about the build process in terms of software development, we’re talking about the – hopefully automated – tasks required to put together the parts that make up a project. This process is not only about compilation and deployment as you might think now. It also includes tasks such as running tests, generating documentation and reporting.

Maven: Apache Maven is an open source build management tool designed to automate the software development process. I guess this definition is a bit too narrow to fully describe what Maven is all about, so have a read through the what-is-maven article for more details. Maven is primarily used in the Java world, but nothing stops us from using it in APEX development.

What has this APEX Maven plugin to offer? Well, not much for the moment. It isn’t even available for download yet, so you can consider this post as a sneak preview. Last week I finished the first task (or Mojo in Maven terms) of the plugin and that’s what I’d like to talk about.

The ImportApp Mojo

The goal of this task is fairly simple: import the .sql export file(s) of my APEX application in a target workspace. The technical implementation to make this possible caused me a bit of a headache though. As you probably know by now, Maven is a Java tool, which means that plugins are written entirely in Java code. Java is of course a powerful language, and the best part of it is its platform independent nature. However, I have experienced that Java and Oracle are not best buddies, especially when it comes to running SQL*Plus scripts through Java. I made it work in the end, but it definitely took me more work than I expected.

Assumptions

You need Java and Maven installed on your machine before being able to install the APEX Maven plugin. That’s actually perfectly normal. However, the ImportApp Mojo itself expects you to have SQL*Plus installed. I couldn’t get around this dependency since the APEX export files have SQL*Plus commands all over the place. I could have used OJDBC in case the export files were plain .sql, but alas.

Example usage

I have set up a little demo project to show you how the APEX Maven plugin works. I have exported a random APEX application and put the export file in my project folder.

project folder layout

The src/main/apex folder contains the .sql export file of an APEX application with ID 610. I now want to import that application into workspace TST_BUILD with another ID. We’ll use the ImportApp Mojo for that by including the APEX Maven plugin in the pom.xml which is located in the project root folder. The Project Object Model (POM) file contains the information required to build the project by Maven. Here’s the content of 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/maven-v4_0_0.xsd">

  <modelVersion>4.0.0</modelVersion>
  <groupId>com.contribute</groupId>
  <artifactId>orclapex-maven-plugin-demo</artifactId>
  <version>1.0</version>
  <name>orclapex-maven-plugin-demo</name>

  <build>
    <plugins>
      <plugin>
        <groupId>com.contribute</groupId>
        <artifactId>orclapex-maven-plugin</artifactId>
        <version>1.0</version>

        <configuration>
          <connectionString>localhost:8202/apex.contribute.be</connectionString>
          <username>tst_build</username>
          <password>tst_build</password>
          <sqlplusCmd>/Applications/instantclient_11_2/sqlplus</sqlplusCmd>
          <appExportLocation>src/main/apex</appExportLocation>
          <workspaceName>tst_build</workspaceName>
          <appId>620</appId>
        </configuration>

        <executions>
          <execution>
            <id>app-import</id>
            <phase>compile</phase>
            <goals>
              <goal>import</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

The plugins tag contains one plugin: version 1.0 of the orclapex-maven-plugin. That’s how I instruct Maven to execute the import goal (= ImportApp Mojo) of the APEX Maven plugin with the specified configuration parameters during the compile phase of the build execution process. The configuration section allows us to specify the details of the application import:

• connectionString: The database connection string used in the SQL*Plus login argument.
• username: The database username used to login in SQL*Plus.
• password: The database user’s password.
• sqlplusCmd: The command to start the SQL*Plus executable. The default value is sqlplus if omitted.
• appExportLocation: The relative path to the folder containing the application export file(s).
• workspaceName: The APEX workspace in which you want to import the application.
• appId: The ID for the application to be imported. Omit this parameter to import the application with its original ID.

The project’s build configuration is all set. Now it’s time to run the build by executing Maven on the command line: mvn compile. Compile is a phase in the build lifecycle to which the import goal of the APEX Maven plugin has been assigned. That’s how the ImportApp Mojo gets triggered for execution during the build process. The result of all this is a successfully imported application with id 620 in the workspace TST_BUILD.

The Maven build log contains something we should be all familiar with; the SQL*Plus prompt commands coming from the export file. Take a look at the full build log here.

To be continued

The ImportApp Mojo is only the first step in the process of streamlining the build process for APEX applications with Maven. Other tasks which I’m planning on adding to the APEX Maven plugin are:

• Check for coding standard violations based on user-defined rules. This is actually something I’m working on for the moment. Version 1.0 is almost finished. You’ll hear more from it soon.
• Automatically generate TAPI (Table API) packages as part of the build.
• A task that compiles a target database schema and reports on invalid database objects.
• Some sort of Natural Docs integration for technical documentation generation.
• …

If you have a good idea for another task, just drop a comment below. Also, the APEX Maven plugin is open source and its source code is hosted on GitHub. So let me know if you’re interested in helping me out.