Skip to content

Home

Jump to bottom Edit New page
David Leoni edited this page Jun 6, 2016 · 24 revisions

Ide setup

Guidelines

Guidelines for time representation

Testing

Deployment

Documentation

This wiki only holds information for people wishing to contribute to projects of Open Data in Trentino. For users of the libraries, please refer to user docs templates stored within the projects, like the tod-commons library user docs template

IDE setup

As IDE we currently prefer Eclipse, as seems to have less problems than Netbeans in handling Immutables annotations.

Java and Maven

We use JDK 7 and Maven 3.3.9

Eclipse

Eclipse seems to have less problems than Netbeans in handling Immutables annotations.

Eclipse Setup

File->Import->Maven->Existing Maven project -> select directory where project is -> Click finish

Eclipse formatting
  • download tod-eclipse-format-style.xml file from <a href="../blob/master/tod-eclipse-format-style.xml" target=_"blank">tod-commons repository
  • set the project format style:
right click on newly created project 
-> Properties 
-> Java Code Style 
-> Check Enable project specific settings 

Then as Active Profile, choose Import...  and select  the previously downloaded file.
Eclipse issues

If there are issues in compiling, try the following:

  • update the project frequently with Project->Clean
  • select the project in Project Explorer and hitting F5
  • select the project in Project Explorer and select Delete (will not delete project from disk unless you explicitly say so in pop up). Then do File-Import -> from Maven

Netbeans

Setup

  • Install Netbeans 8.0.2
  • todo write about md plugin?

In theory you just need to open the project and that's it.

NOTE: Currently there is a BIG issue with Netbeans not finding references to generated classes. When you have open two projects that use Immutables, you're likely to see Cannot find symbol errors highlighted in the ide and ExceptionInInitializer errors when running Maven tests with 'compile on save' turned on. In such cases a mvn clean compile should solve the issue. If you get thousands of Cannot find symbol errors, try issuing just one or more mvn compile to narrow down the errors. So if you need to handle many projects Eclipse is a better bet.

Guidelines

Avoiding boilerplate

To avoid the indecent amount of boilerplate required by Java we generate immutable implementations from abstract classes using annotations of immutables.org , so we also follow its idioms. We usually configure immutables by putting annotations @BuilderStyle for big classes and @SimpleStyle for small ones.

Notice that code generation should be done automatically by your IDE when you save the file above and only at compile time, there is no runtime dependency on immutables.org. See [Ide setup section](#id on possible problemse-setup) for more info on possible problems.

Name casing

We follow Google's naming coding style.

Libraries

When a feature is not satisfactorily covered by vanilla Java 7 we use Guava library . Code must work in a Java 7 environment.

Collections

For collections we prefer Guava's immutable collections

Null values

Null values are generally avoided and empty objects used instead. When no good empty object is found (for example for dates), we use null, marking type with JSR-305 @Nullable annotation (we considered using Guava's Optional<T> but is a bit verbose and might give issues with json serialization)

Logging

We use native Java logging (JUL), there's no need to have extra dependencies such as SLF4J.

Exceptions

We don't use checked exceptions (the ones inheriting from Exception) and prefer runtime exceptions (that inherit from RuntimeException), so users can avoid try-catch boilerplate. Thrown exceptions MUST be properly documented.

Internationalization

ICU4J MessageFormat is adopted for localized string templates (although there is no dependency on ICU4J package). In Javascript you can use MessageFormat.js instead.

Gettext Java is suggested.

todo actually Java Unified Expression language used by Validation api may also be a good option... todo write more.

Dates and time

We would like to

  • represent points in time, intervals, durations, and partial dates
  • have immutable objects
  • store the original date as string if it is expressed in natural language and cannot be converted to machine readable format

In brief, in APIs we use:

For single dates: String in ISO8061 format. If the format is not known, we use the original string prepended by unparseable:. When we really want to model timestamps, we use java.sql.Timestamp.

For intervals: For intervals we use our APeriodOfTime data structure.

For durations:

  • ISO 8601 Duration format, like i.e. `P3Y6M4DT12H30M5S` This format can be used when periodicity can be precisely defined (i.e. there is an update every second for sensor data)
  • the empty string, in case duration is unspecified

For simple frequencies: We use a String in one of the following formats:

  • ISO 8601 Duration format, like i.e. `P3Y6M4DT12H30M5S` This format can be used when periodicity can be precisely defined (i.e. there is an update every second for sensor data)
  • DCAT AP profile frequency codes(in particular, the HTML version), like `BIWEEKLY` . Note these codes also include special frequencies such as `UNKNOWN`, `IRREGULAR`, `CONT` and `UPDATE_CONT`
  • A string that can't be parsed as ISO duration nor as DCAT AP frequency codes (i.e. a string in natural language, like 'Every two weeks except during summer'). In this case the string MUST be prepended with `unparseable:`
  • the empty string, in case frequency is unspecified

    • For complex frequencies: todo

    For time manipulations : To do time manipulations, currently Joda looks like the most stable option, but we don't expose its objects in API and as dependency it must be maven shaded. Maybe in the future we can switch to ThreeTen.

    Handling time in Java

    If you're interested in Java time bla bla, here follows a non-mandatory recap of time representation possibilities for single dates, which are roughly 4:

    Java Date, Timestamp, Calendar: These classes are deprecated and not immutable. They also don't handle partial dates. Date is always UTC (number of milliseconds since the Unix epoch, which occurred at midnight January 1st 1970, UTC.). java.sql.Timestamp extends Date and adds a nanoseconds field. Inherits all the problems of Date and adds others, like surprising behaviours when it is considered as a generic Date ignoring the nanoseconds field. Calendar can store the timezone. Careful with Date.toString(), which will use local timezone. More to read on stack overflow .

    String: Using ISO 8061 encoding it's possible to define points in time, partial dates, intervals and durations. It's obviously easy to serialize and immutable. In case original date is in natural language and format is unknown, there is also the option to store it as it is, prepended with unparseable: to prevent interpreting it as ISO8061. Todo how to manage it in Javascript? we need complete ISO 8601 spec support.

    Joda: de facto standard library. Has immutable objects which are quite big and might bring problems on its own when serializing.

    ThreeTen: Java 8 new library for time, made by the same author of Joda. There is also an Extras (as of July 2015 not yet at 1.0) library with things like Interval. ThreeTen and Extras has a backport to Java 6 and 7, but currently some Extras (like Interval) are not backported.

    Dirty Intervals Theory

    A time interval to parse may be bounded, unbounded, completely unknown or have unknown start or end or even have unparseable dates expressed in human language (sic)

    Here are some cases we might have: TODO this is a super draft!

    already splitted? known format? bounded interval? Example do
    n n y 20 Ottobre 2015 - 25 Novembre 2015 save original string
    n y y 2015-10-20/2015-11-25 save original string, parse and split, save parts as ISO 8061
    y n y {start:"20 Ottobre 2015" end: "25 Novembre 2015"} save original string OR OBJECT?, save parts as ISO 8061
    y y y

    Possible fields where to store stuff:

    startDate
endDate

originalStartDate
originalEndDate
originalInterval : String
accurate:
    Representing intervals

    For now we use intervals expressed with in APeriodOfTime data structure. We took inspiration from schema.org and DCAT AP 1.1, which specifies dublin core PeriodOfTime

    schema.org fields:

    startDate

    endDate

    Durations

    todo

    Frequencies

    todo

    Testing

    Tests are normal Junit tests which are run during the build. todo write how to enable logging during testing.

    in the dependencies section, add:

        <dependency>
      <groupId>eu.trentorise.opendata.commons</groupId>
      <artifactId>tod-commons</artifactId>
      <version>X.Y.Z-SNAPSHOT</version>
    </dependency>

    where X.Y.Z is the current version

    Deployment

    To enable deployment, please see tod-super-pom deploy prerequisites

    Snapshot deployment

    Snapshot deployment is done on Sonatype: https://oss.sonatype.org/content/repositories/snapshots/eu/trentorise/opendata/commons/

    with this command:

        mvn clean deploy

    In Netbeans, you can also:

    right click on the project -> Custom -> Deploy to Sonatype

    Documentation

    For documentation we use the program Josman and follow its guidelines

    Creating a new project

    If you create a new project with annotations from Immutables, and no classes are generated, follow this checklist:

    • did you tell maven/ide to use at least java 7 as platform?
    • are annotation processors enabled generally in your ide? If not, enable them or enable them at least on per-app level
    Add a custom footer
    Add a custom sidebar
    Clone this wiki locally