-
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.md 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.14.0 the SIF3 Framework will no longer support Java 6 or 7. The minimum requirement is Java 8. This is the version it must be tested with. It is also enforced with appropriate settings in the pom.xml.
The provider component of the SIF3 Framework requires the Servlet 3.0 specification. It has also been tested with the Servlet 3.1 specification. You must ensure that your development runs with a Servlet version 3.0 and above.
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 "incompatibility" 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 following versions of web- and/or application servers:
- Tomcat v7, v8, v8.5
- JBoss 6 (Free or Licenced version)
- WildFly 10+
- 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 'sif3-common' and 'sif3-infra-common' modules.
There are a number of test and demo classes that form part of the framework. Their intention is two fold:
- Test functionality (in each sif3-xxx module)
- Provide Demo Code on how to use the framework (sif3-demo-web module)
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 (src/main/java) make any assumptions about a data model. Only classes in test directories (src/test/java) may use a locale data model. These test classes do not form part of the final framework libraries.
The SIF3 Framework has a hierarchy of source directories. Since v0.10 that is guaranteed simply by the fact that the framework is a multi-module maven project. The dependency hierarchy is implied by the maven module structure. Please do not change the dependency hierarchy as you may violate intended software layers (i.e. sif3-common module should not have any web layer implementations or infrastructure classes based on the SIF Infrastructure XSD).
The basic module hierarchy is:
sif3-common <- sif3-infra-model <- sif3-infra-common <- sif3-infra-rest.