Pax Development Guidelines - OPS4J

Overview

This page serves as guideline for developing a Pax project, detailing project structure, maven project settings and other.

Generic rules about Pax projects:

must be buildable with Maven 2.
must follow Maven defaults for internal directory structure.
parent project must have a pom packaging

parent project pom must inherit the pax project pom

<parent>
    <groupId>org.ops4j.pax</groupId>
    <artifactId>project</artifactId>
    <version>version</version>
  </parent>

where version to be used is as required preferably the latest version.

inherit directly/indirectly the pom from the parent project
if Maven generated documentation is used, then the src/main/site/ is located in the parent project.
[TODO]

Structure

[TODO]

Projects without modules

[TODO]

Projects with modules

Name of the module must match the name of the artifact.
[TODO]

Package names

Package names must start with org.ops4j.pax and then a name related to artifact/module name.
Any non exported classes should be placed in a package with a name that ends with .internal
[TODO]

OSGi

A module or a project that will end up as a bundle should:

have a bundle packaging
be built using maven-bundle-plugin
have a Bundle Symblic Name (bsn) that follows the following rules:
- if there is no split between the api and implementation, bsn should be equal with the most significant package name (e.g. org.ops4j.pax.web)
- if there is a split between api and implementation, bsn of api bundle should be equal with the most significant package name (e.g. org.ops4j.pax.logging) and the bsn for implemenatation bundle should be the same as the bsn for the api plus ".impl" (e.g. org.pax.web.impl)
- if there are more implementations for the same api the bsn of implementations should be the same as the bsn for the api plus a significant name for the implementation (e.g. org.ops4j.pax.web.jetty, org.pax.web.tomcat)
have a Bundle Version that matches the artifact version
[TODO]

Template for Project parent POM.

<?xml version="1.0" encoding="UTF-8"?>
<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>
  <parent>
    <groupId>org.ops4j.pax</groupId>
    <artifactId>project</artifactId>
    <version>1.9</version>
  </parent>
  <groupId>org.ops4j.pax.[projectname]</groupId>
  <artifactId>[projectname]</artifactId>
  <packaging>pom</packaging>
  <name>OPS4J - [project name, capital first letter]</name>
  <version>0.1.0-SNAPSHOT</version>

  <url>http://www.ops4j.org/projects/<projectname></url>

  <issueManagement>
    <system>jira</system>
    <url>http://issues.ops4j.org/jira/browse/[projectkey]</url>
  </issueManagement>

  <scm>
    <connection>scm:svn:https://scm.ops4j.org/repos/ops4j/projects/[projectname]</connection>
    <developerConnection>scm:svn:https://scm.ops4j.org/repos/ops4j/projects/[projectname]</developerConnection>
  </scm>

  <build>
<!-- If plugin must work on JDK 1.4  -->
    <plugins>
      <plugin>
        <artifactId>maven-compiler-plugin</artifactId>
        <configuration>
          <source>1.4</source>
          <target>1.4</target>
        </configuration>
      </plugin>
    </plugins>
  </build>

  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <configuration>
          <aggregate>true</aggregate>
          <stylesheetfile>${basedir}/src/site/resources/css/javadoc.css</stylesheetfile>
          <excludePackageNames>*.internal:org.ops4j.pax.wicket.samples.*</excludePackageNames>
          <groups>
            <group>
              <title>API</title>
              <packages>org.ops4j.pax.[projectname]</packages>
            </group>
<!-- Additional Groups if Needed -->
          </groups>
        </configuration>
      </plugin>
    </plugins>
  </reporting>

  <modules>
    <module>api</module>
    <module>impl</module>
<!-- whatever modules needed. Directory names should be short and not full artifactId names. -->
  </modules>

  <dependencyManagement>
    <dependencies>
<!-- Example of shared dependency in the project. Add for simplified version management. -->
      <dependency>
        <groupId>javax.servlet</groupId>
        <artifactId>servlet-api</artifactId>
        <version>2.1</version>
        <scope>provided</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>

<!-- Repositories needed to build first time, since the Pax Project POM (parent above) 
     is not in Maven's central repository yet.
-->

  <repositories>
    <repository>
      <id>ops4j-repository</id>
      <name>The OPS4J Repository</name>
      <url>http://repository.ops4j.org/maven2/</url>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </repository>
    <repository>
      <id>central</id>
      <name>Maven Repository Switchboard</name>
      <url>http://repo1.maven.org/maven2</url>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </repository>
  </repositories>
</project>

[projectname] - The name of the project. Example; pax-logging-api
[projectkey] - The JIRA key. Example; PAXLOGGING. To obtain a new key, ask on general@lists.ops4j.org.

Labels