Section : Documentation > Development

DataNucleus Source Code : GitHub Repositories

GitHub

DataNucleus source code is hosted on GitHub and uses the Git (distributed) source code version control system. You can check out from GitHub using the following.

Using SSH: git clone git@github.com:datanucleus/{repository-name}.git

Using HTTPS: git clone https://github.com/datanucleus/{repository-name}.git

Obviously, not everyone will want to check out all DataNucleus project repositories, so use this command for the particular repositories that you require. Note that GitHub repositories are all browsable via the web, for example the DataNucleus Neo4j datastore plugin. Note that all plugin repositories are Maven projects so you need to understand how to build with Maven to build these plugins.

DataNucleus can be easily developed using Maven, Eclipse (plus m2e plugin), or other IDEs (let us know if you write docs for how to develop DataNucleus with a different IDE). You require JDK1.8+, a Git client (to download/commit DataNucleus Git-based projects) and an editor.

[Note that (previous) source code for all versions up to and including 3.3.5 is stored in SourceForge]

GitHub : Plugins

Within the DataNucleus project over on GitHub you have various repositories providing actual DataNucleus plugins. These are currently

datanucleus-core

APIs :
datanucleus-api-jdo
datanucleus-api-jpa
datanucleus-api-rest

Datastores :
datanucleus-cassandra
datanucleus-excel
datanucleus-hbase
datanucleus-json
datanucleus-ldap
datanucleus-mongodb
datanucleus-neo4j
datanucleus-neodatis
datanucleus-odf
datanucleus-rdbms
datanucleus-xml

Type support :
datanucleus-geospatial
datanucleus-guava
datanucleus-jodatime

Others :
datanucleus-cache
datanucleus-jdo-query
datanucleus-jdo-jca
datanucleus-jpa-query
datanucleus-java8

All plugins are independently versioned (master is the latest branch). This is because they have their own lifecycle, and plugins are bundled together into the products (e.g AccessPlatform). So we could have AccessPlatform version 1.1 using version X of a plugin, and AccessPlatform version 2.0 using version Y of that plugin because it needs some new functionality.

Building with Maven

All DataNucleus plugins are Maven projects, with a pom.xml. To build and install the plugin using Maven simply type

mvn clean install

and the plugin is built and installed in your local Maven repository; how simple can it get?. If you are developing some feature that requires updates to, for example core (datanucleus-core), an API (e.g datanucleus-api-jdo) and a datastore (e.g datanucleus-rdbms) then you will need to build these in the same order, core first, then the API, then the datastore.

Building with Eclipse

When building/developing using Eclipse the first thing you need to do is install the Eclipse m2e plugin (if not already done). This means that the build of any plugin will build using Maven (and get its dependencies from Maven). You then need to import all DataNucleus projects you are working on. Since each plugin in Eclipse will build using Maven you dont need to have all dependent projects present too, just the ones youre working on.

GitHub : Tests

In order to test DataNucleus capabilities we have many end-to-end tests. In the GitHub DataNucleus project these are available in the repository tests. Below that you have some framework projects that need building first, then there are tests split by the persistence API they are for (JDO, JPA, REST, etc).

GitHub : Tools

The GitHub DataNucleus project also provides some tools to help in using DataNucleus. The repositories providing tools are

datanucleus-maven-plugin
datanucleus-eclipse-plugin
datanucleus-idea-plugin (not maintained)

Like with all plugins, the tools are independently versioned since they have their own lifecycle.

GitHub : Documentation

The GitHub DataNucleus project also provides the documentation for DataNucleus.

Documentation : datanucleus.org Project Site

DataNucleus has a main site datanucleus.org for the overall project and the commercial services that we offer. This site makes use of a skin responsible for adding header/footer to all docs as well as the dropdown menus. This skin is available in GitHub in the repository docs-datanucleus-skin. Now you need to build/install the skin, by typing

mvn clean install

The documentation is in GitHub in repository docs-datanucleus Now you can build the site itself by typing

mvn clean site

The site is then available under target/site. The documentation is also generated every night from what is in GitHub, and this appears on the website.

Documentation : AccessPlatform Product Site

The documentation for AccessPlatform uses the same Maven process, and also has its own skin. This skin is available in GitHub in repository docs-accessplatform-skin. Now you need to build/install the skin, by typing

mvn clean install

The documentation is in GitHub in repository docs-accessplatform. Now you can build the site itself by typing

mvn clean site

The site is generated under target/site. You can also build a PDF of the docs by typing

mvn pdf:pdf

The PDF is generated under target/pdf. The documentation is also generated every night from what is in GitHub, and this appears on the website.

Coding Standards

Here we provide an overview of the coding standards employed in DataNucleus source code. If you want to work on DataNucleus or contribute code to DataNucleus you are expected to use these coding standards. We know everyone has their own preference but these are ours so you follow them or any contributed code will not be directly included as is. They may differ from Oracles coding conventions but then those are the conventions of some US company and that doesnt mean that they are necessarily the best, the official or any such title. These are ours, so best get used to it ;-).

If you are using Eclipse then we have an XML Configuration to specify in Eclipse.

Here we have some examples of brace policy and other things

package mypackage;

import java.util.LinkedList;

public class MyIntStack
{
    private final LinkedList fStack;

    public MyIntStack()
    {
        fStack = new LinkedList();
    }

    public int pop()
    {
        return ((Integer) fStack.removeFirst()).intValue();
    }

    public void push(int elem)
    {
        fStack.addFirst(new Integer(elem));
    }

    public boolean isEmpty()
    {
        return fStack.isEmpty();
    }
}

Example of indentation

class Example
{
    int[] myArray = {1, 2, 3, 4, 5, 6};
    int theInt = 1;
    String someString = "Hello";
    double aDouble = 3.0;

    void foo(int a, int b, int c, int d, int e, int f)
    {
        switch (a)
        {
            case 0 :
                Other.doFoo();
                break;
            default :
                Other.doBaz();
        }
    }

    void bar(List v)
    {
        for (int i = 0; i < 10; i++)
        {
            v.add(new Integer(i));
        }
    }
}

Example with if else

class Example
{
    void bar()
    {
        do
        {
        }
        while (true);
        try
        {
        }
        catch (Exception e)
        {
        }
    }

    void foo2()
    {
        if (true)
        {
            return;
        }
        if (true)
        {
            return;
        }
        else if (false)
        {
            return;
        }
        else
        {
            return;
        }
    }

    void foo(int state)
    {
        if (true)
        {
            return;
        }
        if (true)
        {
            return;
        }
        else if (false)
        {
            return;
        }
        else
        {
            return;
        }
    }
}

Source Code Licensing

All contributions to the DataNucleus Project must adhere to the Apache 2 license. All contributions must contain the following copyright notice.

/**********************************************************************
Copyright (c) 2016 {your name} and others. All rights reserved.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Contributors:
{year} {contributor1} - {description of contribution}
{year} {contributor2} - {description of contribution}
    ...
**********************************************************************/

Notwithstanding the above, at the discretion of the owners of the project, DataNucleus downloads may include separately licensed code from third parties as a convenience and where permitted by the third party license, provided this is clearly indicated.