LibreCCM
/
libreccm
3
0
Fork 0
Code Issues 10 Pull Requests Packages Releases Wiki Activity

CCM NG: Some informations for developers (as Maven project site) 

git-svn-id: https://svn.libreccm.org/ccm/ccm_ng@3511 8810af33-2d31-482b-a856-94f89814c4df
pull/2/head
jensp 2015-06-29 15:20:50 +00:00
parent 1ddb4028fb
commit e622668b1b
13 changed files with 447 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
README.txt 100644
View File

@ -0,0 +1,20 @@
LibreCCM
========
The documentation of project is provided as Maven project site. To
create the site run
mvn site site:stage
and open the file ./target/staging/index.html in your browser.
To recreate the site run
mvn clean site site:stage
To include integration tests into the reports
mvn clean site site:stage -Pprofile-name
The available profiles are listed in the documentation.

16
ccm-core/pom.xml
View File

@ -8,18 +8,18 @@
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<ccmVersion>3.0.0-SNAPSHOT</ccmVersion>
<!--<ccmVersion>3.0.0-SNAPSHOT</ccmVersion>-->
</properties>
<parent>
<groupId>org.libreccm</groupId>
<artifactId>libreccm-parent</artifactId>
<version>3.0.0-SNAPSHOT</version>
<version>7.0.0-SNAPSHOT</version>
</parent>
<groupId>org.libreccm</groupId>
<artifactId>ccm-core</artifactId>
<version>6.7.0-SNAPSHOT</version>
<!--<version>7.0.0-SNAPSHOT</version>-->
<name>LibreCCM Core</name>
@ -96,7 +96,8 @@
<dependency>
<groupId>org.libreccm</groupId>
<artifactId>ccm-testutils</artifactId>
<version>6.7.0-SNAPSHOT</version>
<version>${project.parent.version}</version>
<!--<version>7.0.0-SNAPSHOT</version>-->
<scope>test</scope>
</dependency>
@ -364,8 +365,8 @@
<reportSets>
<reportSet>
<reports>
<!--<report>dependencies</report>
<report>project-team</report>
<report>dependencies</report>
<!--<report>project-team</report>
<report>mailing-list</report>
<report>cim</report>
<report>issue-tracking</report>-->
@ -374,6 +375,9 @@
</reports>
</reportSet>
</reportSets>
<configuration>
<dependencyLocationsEnabled>false</dependencyLocationsEnabled>
</configuration>
</plugin>
</plugins>
</reporting>

3
ccm-core/src/main/java/org/libreccm/core/User.java
View File

@ -141,7 +141,8 @@ public class User extends Subject implements Serializable {
* the next login.
*/
@Column(name = "password_reset_required")
@SuppressWarnings("PMD.LongVariable") //Name is fine...
//Can't shorten the name without making the name cryptic.
@SuppressWarnings("PMD.LongVariable")
private boolean passwordResetRequired;
/**

11
ccm-core/src/site/apt/index.apt
View File

@ -1,4 +1,15 @@
--------------
Overview
--------------
Jens Pelzetter
--------------
2015-06-29
--------------
LibreCCM Core
The <Core> module module (<<<ccm-core>>>) for <LibreCCM> provides several
basic services for all other modules of LibreCCM.
For a detailed description of the classes and packages please refer to the
JavaDoc.

4
ccm-core/src/site/site.xml
View File

@ -5,6 +5,10 @@
http://maven.apache.org/xsd/decoration-1.3.0.xsd">
<body>
<menu name="Parent project">
<item name="LibreCCM" href="../index.html"/>
</menu>
<menu name="Overview">
<item name="The Core module" href="index.html"/>
</menu>

21
ccm-shortcuts/pom.xml
View File

@ -1,5 +1,7 @@
<?xml version="1.0"?>
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/xsd/maven-4.0.0.xsd"
xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<modelVersion>4.0.0</modelVersion>
@ -10,12 +12,12 @@
<parent>
<groupId>org.libreccm</groupId>
<artifactId>libreccm-parent</artifactId>
<version>3.0.0-SNAPSHOT</version>
<version>7.0.0-SNAPSHOT</version>
</parent>
<groupId>org.libreccm</groupId>
<artifactId>ccm-shortcuts</artifactId>
<version>6.7.0-SNAPSHOT</version>
<!--<version>7.0.0-SNAPSHOT</version>-->
<name>LibreCCM Shortcuts</name>
@ -39,7 +41,8 @@
<dependency>
<groupId>org.libreccm</groupId>
<artifactId>ccm-core</artifactId>
<version>6.7.0-SNAPSHOT</version>
<!--<version>7.0.0-SNAPSHOT</version>-->
<version>${project.parent.version}</version>
</dependency>
<dependency>
@ -72,7 +75,8 @@
<dependency>
<groupId>org.libreccm</groupId>
<artifactId>ccm-testutils</artifactId>
<version>6.7.0-SNAPSHOT</version>
<!--<version>7.0.0-SNAPSHOT</version>-->
<version>${project.parent.version}</version>
<scope>test</scope>
</dependency>
@ -305,8 +309,8 @@
<reportSets>
<reportSet>
<reports>
<!--<report>dependencies</report>
<report>project-team</report>
<report>dependencies</report>
<!--<report>project-team</report>
<report>mailing-list</report>
<report>cim</report>
<report>issue-tracking</report>-->
@ -315,6 +319,9 @@
</reports>
</reportSet>
</reportSets>
<configuration>
<dependencyLocationsEnabled>false</dependencyLocationsEnabled>
</configuration>
</plugin>
</plugins>
</reporting>

11
ccm-testutils/pom.xml
View File

@ -1,5 +1,7 @@
<?xml version="1.0"?>
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/xsd/maven-4.0.0.xsd"
xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<modelVersion>4.0.0</modelVersion>
@ -10,12 +12,12 @@
<parent>
<groupId>org.libreccm</groupId>
<artifactId>libreccm-parent</artifactId>
<version>3.0.0-SNAPSHOT</version>
<version>7.0.0-SNAPSHOT</version>
</parent>
<groupId>org.libreccm</groupId>
<artifactId>ccm-testutils</artifactId>
<version>6.7.0-SNAPSHOT</version>
<!--<version>7.0.0-SNAPSHOT</version>-->
<name>LibreCCM Test Utilities</name>
<url>http://www.libreccm.org/modules/ccm-testutils</url>
@ -177,6 +179,9 @@
</reports>
</reportSet>
</reportSets>
<configuration>
<dependencyLocationsEnabled>false</dependencyLocationsEnabled>
</configuration>
</plugin>
</plugins>
</reporting>

6
pom.xml
View File

@ -5,15 +5,15 @@
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<ccmVersion>3.0.0-SNAPSHOT</ccmVersion>
<!--<ccm.version>7.0.0-SNAPSHOT</ccm.version>-->
</properties>
<groupId>org.libreccm</groupId>
<artifactId>libreccm-parent</artifactId>
<version>3.0.0-SNAPSHOT</version>
<version>7.0.0-SNAPSHOT</version>
<packaging>pom</packaging>
<name>LibreCCM 3.0.0</name>
<name>LibreCCM</name>
<url>http://www.libreccm.org</url>
<distributionManagement>
<site>

26
src/site/apt/building.apt 100644
View File

@ -0,0 +1,26 @@
-----------------
Building LibreCCM
-----------------
Jens Pelzetter
-----------------
2015-06-29
-----------------
Building LibreCCM
LibreCCM uses Maven 3 for building. The project itself is a multi module
project. At the moment your viewing the project page of the parent project.
Building LibreCCM is done using the standard Maven commands.
To control some features Maven profiles are used. Especially for testing.
These profiles are documented on the {{{./testing.html}Testing LibreCCM}}
page.
* Cheat sheet for building LibreCCM
The following commands must be executed from the directory of the parent
project.
[Build or refresh project site] mvn clean site site:stage
[Create WAR files] ToDo

201
src/site/apt/code-conventions.apt 100644
View File

@ -0,0 +1,201 @@
-------------------------
LibreCCM Code Conventions
-------------------------
Jens Pelzetter
-------------------------
2015-06-29
-------------------------
LibreCCM Code Conventions
The LibreCCM project uses the following code conventions.
* Target language and platform
The target language of the project is Java 7. At the moment we can't
rely on the availability of Java 8 on the systems our users want to install
LibreCCM. LibreCCM also uses the
{{{http://www.jcp.org/en/jsr/detail?id=342}Java EE 7 platform}}. In
particular LibreCCM makes heavy use of the following APIs from the
Java EE 7 standard:
* {{{http://www.jcp.org/en/jsr/detail?id=338}Java Persistence API (JPA) 2.1}}
* {{{http://www.jcp.org/en/jsr/detail?id=340}Servlet 3.1}}
* {{{http://www.jcp.org/en/jsr/detail?id=346}Context and Dependency Injection for the Java EE platform (CDI) 1.1}}
[]
In consequence LibreCCM requires a Java EE compatible application server
to like {{{http://wildfly.org/}Wildfly 8}} to run. We will stay as close to
the standard as possible, but in some cases we will enforce a specific
implementation.
* Coding style
The LibreCCM project uses the the
{{{http://google.github.io/styleguide/javaguide.html}Google Java Style}}
with the following modifications:
[Block indentation] 4 spaces
[Column limit (line length)] 80 characters
[Imports] Star imports are allowed for static imports
** Imports ordering
* All static import in a single group
* All imports from com.arsdigita, org.libreccm, org.librecms, org.aplaws and
org.scientificcms
* Third-party imports, in group per top-level package in ACSII sort order
* java imports
* javax imports
* Style checking
The ensure good code quality the LibreCCM project uses
{{{http://findbugs.sourceforge.net/}FindBugs}} and
{{{http://pmd.sourceforge.net/}PMD}} to check the code for potential bugs
and other problems. Code for the official modules <<must>> pass all
checks from FindBugs and must follow the followings rule sets from PMD:
* {{{http://pmd.sourceforge.net/pmd-5.3.2/pmd-java/rules/java/basic.html}Basic}}
* {{{http://pmd.sourceforge.net/pmd-5.3.2/pmd-java/rules/java/braces.html}Braces}}
* {{{http://pmd.sourceforge.net/pmd-5.3.2/pmd-java/rules/java/clone.html}Clone}}
* {{{http://pmd.sourceforge.net/pmd-5.3.2/pmd-java/rules/java/codesize.html}Code Size}}
* {{{http://pmd.sourceforge.net/pmd-5.3.2/pmd-java/rules/java/design.html}Design}}
* {{{http://pmd.sourceforge.net/pmd-5.3.2/pmd-java/rules/java/empty.html}Empty code}}
* {{{http://pmd.sourceforge.net/pmd-5.3.2/pmd-java/rules/java/finalizers.html}Finalizers}}
* {{{http://pmd.sourceforge.net/pmd-5.3.2/pmd-java/rules/java/imports.html}Import statements}}
* {{{http://pmd.sourceforge.net/pmd-5.3.2/pmd-java/rules/java/javabeans.html}Java Beans}}
* {{{http://pmd.sourceforge.net/pmd-5.3.2/pmd-java/rules/java/naming.html}Naming}}
* {{{http://pmd.sourceforge.net/pmd-5.3.2/pmd-java/rules/java/optimizations.html}Optimizations}}
* {{{http://pmd.sourceforge.net/pmd-5.3.2/pmd-java/rules/java/strictexception.html}Strict exception}}
* {{{http://pmd.sourceforge.net/pmd-5.3.2/pmd-java/rules/java/strings.html}String and StringBuffer}}
* {{{http://pmd.sourceforge.net/pmd-5.3.2/pmd-java/rules/java/sunsecure.html}Security Code Guidelines}}
* {{{http://pmd.sourceforge.net/pmd-5.3.2/pmd-java/rules/java/typeresolution.html}Type resolution}}
* {{{http://pmd.sourceforge.net/pmd-5.3.2/pmd-java/rules/java/unnecessary.html}Unnecessary}}
* {{{http://pmd.sourceforge.net/pmd-5.3.2/pmd-java/rules/java/unusedcode.html}Unused code}}
[]
In some cases it might necessary to suppress warnings. For FindBugs this can
be done using the <<<edu.umd.cs.findbugs.annotations.SuppressWarnings>>>
annotation (see {{http://findbugs.sourceforge.net/manual/annotations.html}}.
To do that it is necessary to add the following dependency to the POM of the
module:
--------------------------------------------------------------------------------
<dependency>
<groupId>net.sourceforge.findbugs</groupId>
<artifactId>annotations</artifactId>
<version>1.3.2</version>
<scope>provided</scope>
</dependency>
-------------------------------------------------------------------------------
The scope here is <<<provided>>> because to necessary JAR file has already
been added due to the use of the FindBugs Maven plugin.
For PMD the standard annotation <<<@SuppressWarnings>>> can be used:
--------------------------------------------------------------------------------
@SuppressWarning("PMD.$rulename")
--------------------------------------------------------------------------------
where <<<$rulename>>> is the name of rule. For example if you have a
variable which name is longer than 17 characters and you can't shorten the
name without making the name cryptic. Example:
--------------------------------------------------------------------------------
...
SuppressWarnings("PMD.LongVariable")
private boolean passwordResetRequired;
...
--------------------------------------------------------------------------------
In this case it is not possible to shorten the name of the variable without
making the name of the variable cryptic. The names of the rules can be found
in the PMD documentation (see links to the rulesets above).
In every case each usage of
<<<edu.umd.cs.findbugs.annotations.SuppressWarnings>>> or
<<<java.lang.SuppressWarnings>>> must be accompanied by an comment in the
same line or above the usage of the <<<SuppressWarnings>>> annotation.
For example
--------------------------------------------------------------------------------
...
SuppressWarnings("PMD.LongVariable") //Name is fine
private boolean passwordResetRequired;
...
--------------------------------------------------------------------------------
or (better)
--------------------------------------------------------------------------------
...
//Can't reduce the name without making the name cryptic
SuppressWarnings("PMD.LongVariable")
private boolean passwordResetRequired;
...
--------------------------------------------------------------------------------
* Package and class names
Official modules should use on the following packages depending to which
subproject they belong:
*-------------------------*----------------------------------------------------*
| <<<org.libreccm>>> | Core components or other common components |
*-------------------------*----------------------------------------------------*
| <<<org.librecms>>> | Common content management components including |
| | common content types like Article or NewsItem |
*-------------------------*----------------------------------------------------*
| <<<org.aplaws>>> | Classes of modules for usage by local authorities |
| | or other public organisations |
*-------------------------*----------------------------------------------------*
| <<<org.scientificcms>>> | Classes of modules for Scientific research |
| | organisations, universities etc. |
*-------------------------*----------------------------------------------------*
Try to avoid class prefixes or long class names. Instead add an additional
level to the package hierarchy. Use descriptive names for the packages.
Package and class names should be chosen to be intuitive. A new developer
should be able to figure out the the general purpose of a class solely
by its package and name.
A practical example: Each content type should get its own package. Instead
of <<<org.librecms.contenttypes.SomeFanyContentTypeInitalizer>>> use
<<<org.librecms.contenttypes.somefanytype.Initalizer>>>.
This rules apply only for package and classes in the official modules.
Third-party modules should use the name of the organisation as package, plus
the name of the official parent project. For example a custom module for
LibreCMS, for instance a new content type, should use
<<<org.example.librecms.contenttypes.somefancytype>>> as package. When
a third-party module is promoted to an official module it has to be
refactored.

39
src/site/apt/index.apt
View File

@ -1,3 +1,40 @@
--------------
Overview
--------------
Jens Pelzetter
--------------
2015-06-29
--------------
LibreCCM
Bla Bla
LibreCCM is a highly advanced (Web-) Content Management System based
on Java EE.
This is the next generation variant of LibreCCM. In this version which
currently developed in parallel the current version, several custom APIs
like the persistence layer have been replaced with standard APIs from
Java Community process.
Please note that this is a project in its early phase of development. Some
aspects may change without warning.
The most notable change is the move the JPA as
persistence layer. We are using Hibernate as implementation because
Hibernate currently provides one important feature which other JPA providers
do not provide: Versioned or better audited entities. This extension is
called Envers. Auditing is currently not part the JPA standard therefore
we need to use s specific implementation.
Another notable change is that the build system is now using
{{{http://maven.apache.org/}Apache Maven}}. The project is a standard
multi module project. More informations can be found at the
{{{./building.html}Building LibreCCM}} page.
For testing {{{http://junit.org/}JUnit 4}} is used. For testing Java EE
components like CDI beans the {{{http://arquillian.org/}Arquillian}} testing
platform is used. More details about the test system can be found on the
{{{./testing.html}Testing LibreCCM}} page.
Please note that this documentation is work in progress and is may
incomplete.

105
src/site/apt/testing.apt 100644
View File

@ -0,0 +1,105 @@
----------------
Testing LibreCCM
----------------
Jens Pelzetter
----------------
2015-06-29
----------------
Testing LibreCCM
For testing the LibreCCM uses JUnit 4 and Arquillian. Arquillian is a
testing platform developed by JBoss/RedHat for testing Java EE applications
<<inside>> an Application Server. Arquillian integrates with JUnit using
a <<<TestRunner>>>.
This page only describes the special aspects of testing LibreCCM. For an
introduction to Arquillian please refer to the webpage and documentation
of Arquillian.
* Controlling which tests to are executed
All tests are annotated with a category using the category feature from
JUnit. Test which are annotated with
--------------------------------------------------------------------------------
@Category(UnitTest.class)
--------------------------------------------------------------------------------
are executed in every case. Tests which are annotated with
--------------------------------------------------------------------------------
@Category(IntegrationTest.class)
--------------------------------------------------------------------------------
are only executed when special Maven profiles are used. These profiles are
used to control against which Application server Arquillan should run its
tests.
* Available profiles
At the moment the following profiles are provided:
[wildfly8-embedded] Uses an embedded Wildfly 8 server and the integrated H2
database-
[wildfly8-remote-h2-mem] Uses a remote Wildfly 8 application server and
a in memory H2 database
[wildfly8-remote-mysql] Uses a remote Wildfly 8 application server and
a MySQL or MariaDB database.
[wildfly8-remote-pgsql] Uses a remote Wildfly 8 application server and
a PostgreSQL database.
Please note that the profiles must be defined separately in each module.
Therefore maybe not all modules will provide all modules (but they should).
* Planned profiles
The following profiles are planned to be added:
[wildfly8-remote-oracle] Will use a remote Wildfly 8 server and a Oracle
database.
[tomee17-embedded] Will use a embedded TomEE application server, version 1.7
[tomee17-remote-mysql] Will use a remote TomEE application server and a
MySQL/MariaDB database.
[tomee17-remote-pgsql] Will use a remote TomEE application server and a
PostgreSQL database.
* Structure of the profiles
For each profile their is separate resource directory in the
<<<src/test/resources>>> directory of the module which at least
contains these files:
[arquillian.xml] Configuration file for Arquillian.
[test-persistence.xml] JPA configuration file. Will be renamed to
<<<persistence.xml>>> and placed into the test archive by the deploy method
of the test. On important difference to the production <<<persistence.xml>>>
is that the <<<test-persistence.xml>>> configures Hibernate to automatically
drop the database and recreate the schema. The production
<<<persistence.xml>>> is configured to only verify the schema. Schema
creation and migrations are done by LibreCCM.
* Preparing the remote Application Servers
** Wildfly 8
For using the remote profiles you have to install a Wildfly application
server on the system you want to run the tests on an configure these
datasources:
[java:/comp/env/jdbc/org/libreccm/ccm-core/h2-mem] A in memory database
using the H2 database which is part of Wildfly.
[java:/comp/env/jdbc/org/libreccm/ccm-core/mysql] MySQL database
[java:/comp/env/jdbc/org/libreccm/ccm-core/pgsql] PostgresSQL database
Please note that the database is recreated after each test. Therefore
you should not use a production database.

4
src/site/site.xml
View File

@ -14,7 +14,11 @@
<body>
<menu name="Overview">
<item name="Overview" href="index.html"/>
<item name="Code conventions" href="code-conventions.html"/>
<item name="Building LibreCCM" href="building.html"/>
<item name="Testing LibreCCM" href="testing.html"/>
</menu>
<menu ref="modules"/>
<menu ref="reports"/>
</body>