-
Notifications
You must be signed in to change notification settings - Fork 10
Contributing to Sif 3 Framework Java
This document is geared towards developers that wish to contribute to the SIF3 Framework. It lists some core constraints as well as some common policies and uses of the SIF3 Framework code base. There is a detailed readme.txt at the root level of the project code that holds information about version history and upgrade instructions between different versions.
Generally,please apply standard Git practices for forks, branches, pull requests and so on. If you are unfamiliar with these terms and practices you can read up on it on appropriate GitHub documentation. The branching structure used for this framework is based on the article A successful Git branching model.
To reduce unnecessary work for others, please structure your contributions into grouped, tested, working patches before offering them to the administrators. For guidelines about this and other good practices, refer to the article Commit Often, Fix it Later, Publish Once: Git Best Practices.
The Java version of the SIF3 Framework has been used in a number of high profile projects with some constraints on what changes may be allowed. This mainly relates to environments the framework has been tested in. If you want to contribute code to this framework, you must ensure that these environments are considered and that the code works with them. The list below highlights the core points to take into account when developing and testing your code.
Since v0.9.0 the SIF3 Framework will no longer support Java 6. The minimum requirement is Java 7. This is the version it must be tested with. While it is acknowledged that Java 8 is a much more recent version there are still core projects that use Java 7. Therefore you must ensure that you compile, build and test your additions/bug fixes with Java 7. Avoid Java 8 features such as the new Date/Time libraries or Lambda notations.
The provider component of the SIF3 Framework requires the Servlet 3.0 specification. You must ensure that your development runs with that Servlet version.
JAX-RS is the Java specification for REST web-services. The SIF3 Framework uses JAX-RS annotations. While the code base uses the Jersey implementation of the JAX-RS it has also been tested with JBoss RestEasy, which is an alternate JAX-RS implementation. As with previous points you must ensure and test your changes with Jersey and RestEasy JAX-RS implementations. In the past we have found that some regular expressions used in annotations do not always work with RestEasy as intended and simple changes to a regular expression in an annotation may fix "incompatibilty" issues. So if you use annotations in the REST Webservice implementation, you must test them with both JAX-RS implementations.
The SIF3 Framework has been used with a number of Java web- and/or application servers. While we cannot test with all of them there is a sub-set we take into account in our tests. Code that is provided to the framework that touches on web-service functionality must be tested with the follwoing versions of web- and/or application servers:
- Tomcat v7
- JBoss 6 (Free or Licenced version)
- Optionally Jetty 8
The list above mentions a minimum version number. It must be ensured that the code you provide runs on these versions. Of course it is fine if it runs on newer versions as well 😃.
The SIF3 Framework has two core components. One relates to consumers (client side) and one relates to providers (server side). Many classes are common to both and changes in these classes affect both components. When altering the code base in any way you must always consider and test the impact for consumers and providers. The prime candidates of classes that are used in both components are in the 'sif3Common' and 'sif3InfraCommon' source directories.
There are a number of test and demo classes that form part of the framework. Their intention is two fold:
- Test functionality
- Provide Demo Code on how to use the framework
It is important to note that these test and demo classes are based around the SIF AU Data Model. This doesn't mean that the framework is tied to that data model at all. None of the classes used in any source directory starting with 'sif3' make any assumptions about a data model. Only classes in the directories with a pre-fix 'sif3' form the framework code.
The SIF3 Framework has a hierarchy of source directories. It determines which package can import classes from which other package. You can verify that the import dependencies aren't broken by running the appropriate ant task. Run them in the following order to ensure that no package hierarchy is violated:
- 02-clean
- 03-jar-components
If you get no compilation errors that relate to imports then your dependency hierarchy is correct. Generally the hierarchy is:
sif3Common<-sif3InfraModel<-sif3InfraCommon<-sif3InfraREST.