Create README.md

Author: joerghuber

README.md

@@ -0,0 +1,72 @@
+# sif3-framework-java
+This readme 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 more detailed readme.txt at the root level of the project code that holds information about
+version history and upgrade instructions between different versions.
+
+Generally standard Git practices for forks, branches, pull requests etc. do apply. If you are not familiar
+with these terms and practices you can read up on it on appropriate GitHub documentation. It is out of the scope
+of this readme to repeat those procedures.
+
+## What do I need to consider if I want to provide code to this SIF3 Framework Repository?
+The Java version of the SIF3 Framework has been used in a number of high profile projects who have
+some constraints what they use and allow. This does mainly relate to environments the framework has been tested
+on and with. 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.
+
+### Java Version
+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 and 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.
+
+### Servlet Version
+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
+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.
+
+### Web- and Application Servers
+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 :smiley:. 
+
+### Components of the Framework
+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.
+
+### Test Classes and Data Model
+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.
+
+### Source Code dependencies
+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:
+
+1. 02-clean
+2. 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.
+