<commit_before>= Estatio: an open source estate management system.

Estatio is modern and flexible property management software.
It offers real estate professionals and service providers the power and flexibility to manage their business in a superior, flexible and cost-effective manner.


== Screenshots

The following screenshots (taken 13 december 2014) correspond to the business logic in Estatio's link:https://github.com/estatio/estatio/tree/master/estatioapp/dom/src/main/java/org/estatio/dom[domain object model].

=== All properties

image::https://raw.github.com/estatio/estatio/master/docs/screenshots/AllProperties.png[width="600px",link="https://raw.github.com/estatio/estatio/master/docs/screenshots/AllProperties.png"]

image::https://raw.github.com/estatio/estatio/master/docs/screenshots/AllProperties-Map.png[width="600px",link="https://raw.github.com/estatio/estatio/master/docs/screenshots/AllProperties-Map.png"]

=== Lease

image::https://raw.github.com/estatio/estatio/master/docs/screenshots/Lease.png[width="600px",link="https://raw.github.com/estatio/estatio/master/docs/screenshots/Lease.png"]

=== LeaseItem

image::https://raw.github.com/estatio/estatio/master/docs/screenshots/LeaseItem.png[width="600px",link="https://raw.github.com/estatio/estatio/master/docs/screenshots/LeaseItem.png"]

=== Invoice

image::https://raw.github.com/estatio/estatio/master/docs/screenshots/Invoice.png[width="600px",link="https://raw.github.com/estatio/estatio/master/docs/screenshots/Invoice.png"]


== Trying out Estatio

=== Building Estatio

==== Prereqs

Estatio runs on Java and is built with http://maven.apache.org[Maven].
The source code is managed using https://help.github.com/articles/set-up-git[git], and is held on http://github.com[github].

If you don't already have them installed, install Java (JDK 6 or later), Maven (3.0.4 or later), and git.

==== Download and build Estatio

Estatio is built using maven.

Download using git:

[source]
----
git clone https://github.com/estatio/estatio.git
cd estatio
----

and build using maven:

[source]
----
mvn clean install -Pjetty-console
----

The clone is approx 70Mb, and takes approximately 1 minute to build.


=== Configure Estatio (JDBC URL)

Before Estatio can be run, you must configure its JDBC URL; typically this lives in the `webapp/src/main/webapp/WEB-INF/persistor.properties` properties file.

You can do this most easily by copying a set of property entries from `webapp/src/main/webapp/WEB-INF/persistor-SAMPLE.properties`.

For example, to run against an in-memory HSQLDB, the `persistor.properties` file should consist of:

[source]
----
isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionDriverName=org.hsqldb.jdbcDriver
isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionURL=jdbc:hsqldb:mem:test
isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionUserName=sa
isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionPassword=
----

The JDBC driver for HSQLDB is on the classpath.
If you want to connect to some other database, be sure to update the `pom.xml` to add the driver as a `<dependency>`.

=== Run Estatio

You can run Estatio either using the standalone (self-hosting) version of the WAR, or using `mvn jetty plugin`.

* Running as a self-hosting JAR +
+
Run using: +
+
[source]
----
java -jar estatioapp/webapp/target/estatio-webapp-x.y.z-SNAPSHOT-jetty-console.war
----
+
(where `x.y.z` is the current version), and press the 'start button'.

* Running through Maven +
+
Run using: +
+
[source]
----
cd estatioapp/webapp
mvn jetty:run
----

Once the app has started, browse to:

[source]
----
http://localhost:8080/wicket/
----

=== Using Estatio

* Login using `estatio-admin/pass` or `estatio-user/pass`.

* Install some demo fixtures:

** Administration > Install Demo Fixtures

* Run a script to setup invoices:

** Administration > Run script: GenerateTopModelInvoice

And take a look around :-)

If you encounter any bugs, do https://github.com/estatio/estatio/blob/master/pom.xml#L70[let us know].


=== Implementation

Estatio consists of multiple modules, deployed as a single WAR (a "modular monolith").
These modules are layered as follows:

image::https://raw.githubusercontent.com/estatio/estatio/master/docs/images/modules.png[]

At the bottom is http://isis.apache.org[Apache Isis] framework.
The Estatio application and modules depend on the framework in that its domain objects are annotated with Apache Isis and DataNucleus annotations, and use domain services provided by Apache Isis (such as `RepositoryService` and `TitleService`).

On top of that are a number of modules from http://www.isisaddons.org[Isis Addons].  
These address technical cross-cutting concerns such as security, auditing, publishing, freemarker mail-merge and so-on.
The Estatio domain objects don't (tend to) have any dependencies on these modules (though there are one or two mixins to allow the audit trail to be viewed, for example).

At about the same level of abstraction are a modules provided by the http://catalog.incode.org[Incode Catalog].
These provide functionality for various generic business subdomains, such as documents, notes, aliases and classifications.
This functionality is expected/hoped to be reusable across multiple different applications.

On top of these are a number of Wicket UI components, also provided by http://isisaddons.org[Isis Addons].
Like the modules, the Estatio domain objects don't (tend to) have any dependencies on these Wicket UI components; the one exception is that objects that can be rendered on a map must implement the `Locatable` interface.

On top of the generic business domain modules are the modules that contain the Estatio domain objects themselves, residing in _this_ git repo.
To ensure modularity, these reside in separate maven modules, but are versioned together with all of them sharing a single parent `pom.xml`.
There is some integration between Estatio domain objects and these generic subdomains, for example to allow ``Document``s to be attached to various domain objects (such as `Invoice` etc).

Finally there is the Estatio application itself. 
This also consists of further maven module in _this_ git repo, notably the `estatio-app` module (defining the `EstatioAppManifest` and a number of menu services) and the `estatio-webapp` module (which configures the various UI components and builds the WAR file).


=== Support

You are free to adapt or extend Estatio to your needs.
If you would like assistance in doing so, go to http://www.estatio.org[www.estatio.org].

You can find plenty of help on using Apache Isis at the http://isis.apache.org/support.html[Isis mailing lists].
There is also extensive http://isis.apache.org/documentation.html[online documentation].


== Developers' Guide

This section contains useful info for the Estatio developers themselves.


=== Multi-module development
<commit_msg>updates README developers' guide with format of commit messages<commit_after>= Estatio: an open source estate management system.

Estatio is modern and flexible property management software.
It offers real estate professionals and service providers the power and flexibility to manage their business in a superior, flexible and cost-effective manner.


== Screenshots

The following screenshots (taken 13 december 2014) correspond to the business logic in Estatio's link:https://github.com/estatio/estatio/tree/master/estatioapp/dom/src/main/java/org/estatio/dom[domain object model].

=== All properties

image::https://raw.github.com/estatio/estatio/master/docs/screenshots/AllProperties.png[width="600px",link="https://raw.github.com/estatio/estatio/master/docs/screenshots/AllProperties.png"]

image::https://raw.github.com/estatio/estatio/master/docs/screenshots/AllProperties-Map.png[width="600px",link="https://raw.github.com/estatio/estatio/master/docs/screenshots/AllProperties-Map.png"]

=== Lease

image::https://raw.github.com/estatio/estatio/master/docs/screenshots/Lease.png[width="600px",link="https://raw.github.com/estatio/estatio/master/docs/screenshots/Lease.png"]

=== LeaseItem

image::https://raw.github.com/estatio/estatio/master/docs/screenshots/LeaseItem.png[width="600px",link="https://raw.github.com/estatio/estatio/master/docs/screenshots/LeaseItem.png"]

=== Invoice

image::https://raw.github.com/estatio/estatio/master/docs/screenshots/Invoice.png[width="600px",link="https://raw.github.com/estatio/estatio/master/docs/screenshots/Invoice.png"]


== Trying out Estatio

=== Building Estatio

==== Prereqs

Estatio runs on Java and is built with http://maven.apache.org[Maven].
The source code is managed using https://help.github.com/articles/set-up-git[git], and is held on http://github.com[github].

If you don't already have them installed, install Java (JDK 6 or later), Maven (3.0.4 or later), and git.

==== Download and build Estatio

Estatio is built using maven.

Download using git:

[source]
----
git clone https://github.com/estatio/estatio.git
cd estatio
----

and build using maven:

[source]
----
mvn clean install -Pjetty-console
----

The clone is approx 70Mb, and takes approximately 1 minute to build.


=== Configure Estatio (JDBC URL)

Before Estatio can be run, you must configure its JDBC URL; typically this lives in the `webapp/src/main/webapp/WEB-INF/persistor.properties` properties file.

You can do this most easily by copying a set of property entries from `webapp/src/main/webapp/WEB-INF/persistor-SAMPLE.properties`.

For example, to run against an in-memory HSQLDB, the `persistor.properties` file should consist of:

[source]
----
isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionDriverName=org.hsqldb.jdbcDriver
isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionURL=jdbc:hsqldb:mem:test
isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionUserName=sa
isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionPassword=
----

The JDBC driver for HSQLDB is on the classpath.
If you want to connect to some other database, be sure to update the `pom.xml` to add the driver as a `<dependency>`.

=== Run Estatio

You can run Estatio either using the standalone (self-hosting) version of the WAR, or using `mvn jetty plugin`.

* Running as a self-hosting JAR +
+
Run using: +
+
[source]
----
java -jar estatioapp/webapp/target/estatio-webapp-x.y.z-SNAPSHOT-jetty-console.war
----
+
(where `x.y.z` is the current version), and press the 'start button'.

* Running through Maven +
+
Run using: +
+
[source]
----
cd estatioapp/webapp
mvn jetty:run
----

Once the app has started, browse to:

[source]
----
http://localhost:8080/wicket/
----

=== Using Estatio

* Login using `estatio-admin/pass` or `estatio-user/pass`.

* Install some demo fixtures:

** Administration > Install Demo Fixtures

* Run a script to setup invoices:

** Administration > Run script: GenerateTopModelInvoice

And take a look around :-)

If you encounter any bugs, do https://github.com/estatio/estatio/blob/master/pom.xml#L70[let us know].


=== Implementation

Estatio consists of multiple modules, deployed as a single WAR (a "modular monolith").
These modules are layered as follows:

image::https://raw.githubusercontent.com/estatio/estatio/master/docs/images/modules.png[]

At the bottom is http://isis.apache.org[Apache Isis] framework.
The Estatio application and modules depend on the framework in that its domain objects are annotated with Apache Isis and DataNucleus annotations, and use domain services provided by Apache Isis (such as `RepositoryService` and `TitleService`).

On top of that are a number of modules from http://www.isisaddons.org[Isis Addons].  
These address technical cross-cutting concerns such as security, auditing, publishing, freemarker mail-merge and so-on.
The Estatio domain objects don't (tend to) have any dependencies on these modules (though there are one or two mixins to allow the audit trail to be viewed, for example).

At about the same level of abstraction are a modules provided by the http://catalog.incode.org[Incode Catalog].
These provide functionality for various generic business subdomains, such as documents, notes, aliases and classifications.
This functionality is expected/hoped to be reusable across multiple different applications.

On top of these are a number of Wicket UI components, also provided by http://isisaddons.org[Isis Addons].
Like the modules, the Estatio domain objects don't (tend to) have any dependencies on these Wicket UI components; the one exception is that objects that can be rendered on a map must implement the `Locatable` interface.

On top of the generic business domain modules are the modules that contain the Estatio domain objects themselves, residing in _this_ git repo.
To ensure modularity, these reside in separate maven modules, but are versioned together with all of them sharing a single parent `pom.xml`.
There is some integration between Estatio domain objects and these generic subdomains, for example to allow ``Document``s to be attached to various domain objects (such as `Invoice` etc).

Finally there is the Estatio application itself. 
This also consists of further maven module in _this_ git repo, notably the `estatio-app` module (defining the `EstatioAppManifest` and a number of menu services) and the `estatio-webapp` module (which configures the various UI components and builds the WAR file).


=== Support

You are free to adapt or extend Estatio to your needs.
If you would like assistance in doing so, go to http://www.estatio.org[www.estatio.org].

You can find plenty of help on using Apache Isis at the http://isis.apache.org/support.html[Isis mailing lists].
There is also extensive http://isis.apache.org/documentation.html[online documentation].


== Developers' Guide

This section contains useful info for the Estatio developers themselves.


=== Commit messages

Use the format:

[source,]
----
EST-xxxx: fixes the yada yada yada
----

that is, specifying the Jira issue number, and then a description of the change in the present tense.

For example: 

* `EST-864: fixes bad reference to country-dom (was -SNAPSHOT, should be 1.13.0)`
* `EST-863 and EST-865: moves base and documentation module out to incode.`
* `EST-861: removes EstatioUserRole, with functionality moved to EstatioRole`


The idea of using present tense is that the commit history, when read back, can be read as: "this patch, if it was applied... "


=== Multi-module development

{'fraction_non_alphanumeric': 0.10055325034578147, 'fraction_numerical': 0.005809128630705394, 'mean_word_length': 4.622472783825817, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 9, 'https://': 30, 'lorem ipsum': 0, 'www.': 6, 'xml': 6}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '557733', 'n_tokens_mistral': 4400, 'n_tokens_neox': 4204, 'n_words': 1552}