diff --git a/README.txt b/README.txt new file mode 100644 index 000000000..088d0842b --- /dev/null +++ b/README.txt @@ -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. + diff --git a/ccm-core/pom.xml b/ccm-core/pom.xml index 75d1c93d3..67c2b3c10 100644 --- a/ccm-core/pom.xml +++ b/ccm-core/pom.xml @@ -8,18 +8,18 @@ UTF-8 - 3.0.0-SNAPSHOT + org.libreccm libreccm-parent - 3.0.0-SNAPSHOT + 7.0.0-SNAPSHOT org.libreccm ccm-core - 6.7.0-SNAPSHOT + LibreCCM Core @@ -96,7 +96,8 @@ org.libreccm ccm-testutils - 6.7.0-SNAPSHOT + ${project.parent.version} + test @@ -364,8 +365,8 @@ - @@ -374,6 +375,9 @@ + + false + diff --git a/ccm-core/src/main/java/org/libreccm/core/User.java b/ccm-core/src/main/java/org/libreccm/core/User.java index bcd64b0f8..90dd83405 100644 --- a/ccm-core/src/main/java/org/libreccm/core/User.java +++ b/ccm-core/src/main/java/org/libreccm/core/User.java @@ -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; /** diff --git a/ccm-core/src/site/apt/index.apt b/ccm-core/src/site/apt/index.apt index dbae22e54..3f02b6272 100644 --- a/ccm-core/src/site/apt/index.apt +++ b/ccm-core/src/site/apt/index.apt @@ -1,4 +1,15 @@ + -------------- + Overview + -------------- + Jens Pelzetter + -------------- + 2015-06-29 + -------------- + LibreCCM Core The module module (<<>>) for provides several - basic services for all other modules of LibreCCM. \ No newline at end of file + basic services for all other modules of LibreCCM. + + For a detailed description of the classes and packages please refer to the + JavaDoc. \ No newline at end of file diff --git a/ccm-core/src/site/site.xml b/ccm-core/src/site/site.xml index 8b30116e5..73e143bc9 100644 --- a/ccm-core/src/site/site.xml +++ b/ccm-core/src/site/site.xml @@ -5,6 +5,10 @@ http://maven.apache.org/xsd/decoration-1.3.0.xsd"> + + + + diff --git a/ccm-shortcuts/pom.xml b/ccm-shortcuts/pom.xml index f8fb5a59b..1df900a80 100644 --- a/ccm-shortcuts/pom.xml +++ b/ccm-shortcuts/pom.xml @@ -1,5 +1,7 @@ - 4.0.0 @@ -10,12 +12,12 @@ org.libreccm libreccm-parent - 3.0.0-SNAPSHOT + 7.0.0-SNAPSHOT org.libreccm ccm-shortcuts - 6.7.0-SNAPSHOT + LibreCCM Shortcuts @@ -39,7 +41,8 @@ org.libreccm ccm-core - 6.7.0-SNAPSHOT + + ${project.parent.version} @@ -72,7 +75,8 @@ org.libreccm ccm-testutils - 6.7.0-SNAPSHOT + + ${project.parent.version} test @@ -305,8 +309,8 @@ - @@ -315,6 +319,9 @@ + + false + diff --git a/ccm-testutils/pom.xml b/ccm-testutils/pom.xml index 545d45a6a..5b04e986c 100644 --- a/ccm-testutils/pom.xml +++ b/ccm-testutils/pom.xml @@ -1,5 +1,7 @@ - 4.0.0 @@ -10,12 +12,12 @@ org.libreccm libreccm-parent - 3.0.0-SNAPSHOT + 7.0.0-SNAPSHOT org.libreccm ccm-testutils - 6.7.0-SNAPSHOT + LibreCCM Test Utilities http://www.libreccm.org/modules/ccm-testutils @@ -177,6 +179,9 @@ + + false + diff --git a/pom.xml b/pom.xml index ad1bcd626..5fe824b0d 100644 --- a/pom.xml +++ b/pom.xml @@ -5,15 +5,15 @@ UTF-8 - 3.0.0-SNAPSHOT + org.libreccm libreccm-parent - 3.0.0-SNAPSHOT + 7.0.0-SNAPSHOT pom - LibreCCM 3.0.0 + LibreCCM http://www.libreccm.org diff --git a/src/site/apt/building.apt b/src/site/apt/building.apt new file mode 100644 index 000000000..6093f69b1 --- /dev/null +++ b/src/site/apt/building.apt @@ -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 \ No newline at end of file diff --git a/src/site/apt/code-conventions.apt b/src/site/apt/code-conventions.apt new file mode 100644 index 000000000..18b8d0676 --- /dev/null +++ b/src/site/apt/code-conventions.apt @@ -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 <> 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 <<>> + 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: + +-------------------------------------------------------------------------------- + + net.sourceforge.findbugs + annotations + 1.3.2 + provided + +------------------------------------------------------------------------------- + + The scope here is <<>> 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 + <<>> or + <<>> must be accompanied by an comment in the + same line or above the usage of the <<>> 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: + +*-------------------------*----------------------------------------------------* +| <<>> | Core components or other common components | +*-------------------------*----------------------------------------------------* +| <<>> | Common content management components including | +| | common content types like Article or NewsItem | +*-------------------------*----------------------------------------------------* +| <<>> | Classes of modules for usage by local authorities | +| | or other public organisations | +*-------------------------*----------------------------------------------------* +| <<>> | 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 <<>> use + <<>>. + + 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 + <<>> as package. When + a third-party module is promoted to an official module it has to be + refactored. \ No newline at end of file diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt index 91eb20524..5ff4e08d8 100644 --- a/src/site/apt/index.apt +++ b/src/site/apt/index.apt @@ -1,3 +1,40 @@ + -------------- + Overview + -------------- + Jens Pelzetter + -------------- + 2015-06-29 + -------------- + LibreCCM - Bla Bla \ No newline at end of file + 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. \ No newline at end of file diff --git a/src/site/apt/testing.apt b/src/site/apt/testing.apt new file mode 100644 index 000000000..768b3e038 --- /dev/null +++ b/src/site/apt/testing.apt @@ -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 + <> an Application Server. Arquillian integrates with JUnit using + a <<>>. + + 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 + <<>> 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 + <<>> and placed into the test archive by the deploy method + of the test. On important difference to the production <<>> + is that the <<>> configures Hibernate to automatically + drop the database and recreate the schema. The production + <<>> 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. \ No newline at end of file diff --git a/src/site/site.xml b/src/site/site.xml index 7732ebc5b..f0d4198d3 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -14,7 +14,11 @@ + + + +