v2.1.0

.github/workflows/main.yml

@@ -4,15 +4,44 @@ jobs:
   build_job: # job name
     runs-on: ubuntu-22.04
     steps:
+      - name: Use JDK 17
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+
       - name: Install libreoffice
         run: sudo apt-get install -y libreoffice
 
       - name: Standard Checkout
         uses: actions/checkout@v3.2.0
 
+      - name: Use JDK 17
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+
       - name: Build with Maven
         run: mvn -Davispa.ecm.office.home='/usr/lib/libreoffice' -B verify
 
+      - name: Upload JaCoCo coverage report
+        uses: actions/upload-artifact@v3.1.1
+        with:
+          name: jacoco-report
+          path: target/site/jacoco/
+
+  generate_badges:
+    runs-on: ubuntu-22.04
+    if: github.ref == 'refs/heads/master' || github.ref == 'refs/heads/develop'
+    needs: build_job
+    steps:
+      - name: Get JaCoCo coverage report
+        uses: actions/download-artifact@v3.0.2
+        with:
+          name: jacoco-report
+          path: target/site/jacoco/
+
       - name: Generate JaCoCo Badge
         uses: cicirello/jacoco-badge-generator@v2.9.0
         with:
@@ -23,15 +52,14 @@ jobs:
           echo "coverage = ${{ steps.jacoco.outputs.coverage }}"
           echo "branch coverage = ${{ steps.jacoco.outputs.branches }}"
 
+      - name: Shallow Checkout
+        uses: actions/checkout@v3.2.0
+        with:
+          fetch-depth: 1
+
       - name: Commit and push the badge (if it changed)
         uses: EndBug/add-and-commit@v9.1.1
         with:
           default_author: github_actions
           message: 'Autogenerated JaCoCo coverage badge'
-          add: '*.svg'
-
-      - name: Upload JaCoCo coverage report
-        uses: actions/upload-artifact@v3.1.1
-        with:
-          name: jacoco-report
-          path: target/site/jacoco/
+          add: '*.svg'

.gitignore

@@ -15,7 +15,8 @@ src/test/resources/configuration/ecm_**
 .sts4-cache
 
 ### IntelliJ IDEA ###
-.idea
+.idea/*
+!.idea/copyright/
 *.iws
 *.iml
 *.ipr

README.md

@@ -3,20 +3,25 @@
 # Avispa ECM
 
 A small framework for implementing basic ECM (Enterprise Content Management) solution. It is a second, more general and
-highly inspired by OpenText Documentum ECM, iteration of previous (not published) solution for knowledge base application.
+highly inspired by OpenText Documentum ECM, iteration of previous (not published) solution for knowledge base
+application.
 
 It provides basic feature for storing and managing documents:
+
 - custom property pages, which can be utilized in any UI application basing on the Avispa ECM
 - using documents templates
-- creation of logical folders structure within an ECM allowing to keep documents in an organized way without any further actions
+- creation of logical folders structure within an ECM allowing to keep documents in an organized way without any further
+  actions
 - auto-generating of documents names
 - possibility of extension and customization to fit the application needs
 - multiple configurations for different document types using custom MongoDB-like query language for conditions resolving
-- auto-generating (thanks to LibreOffice) of so called renditions - pdf variants of original documents 
+- auto-generating (thanks to LibreOffice) of so called renditions - pdf variants of original documents
 
 ## Roadmap
 
-As mentioned at the beginning, Avispa ECM provides support for the basic features only. The high-level roadmap for extension looks like below
+As mentioned at the beginning, Avispa ECM provides support for the basic features only. The high-level roadmap for
+extension looks like below
+
 - basic authentication and authorization mechanisms (now the ECM is designed only for one-person use)
 - localization
 - documents versioning
@@ -30,13 +35,46 @@ As mentioned at the beginning, Avispa ECM provides support for the basic feature
 
 | Property name                        | Description                                                                                                                       |
 |--------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
+| `avispa.ecm.name`                    | Name of the ECM solution                                                                                                          |
 | `avispa.ecm.file-store.path`         | Path where the documents will be physically stored. By default it will be `default-file-store` folder in home directory on `dev`. |
 | `avispa.ecm.file-store.name`         | Name of the file store in the database.                                                                                           |
 | `avispa.ecm.configuration.paths`     | Comma separated paths to `.zip` configuration loaded during tests and `dev` setup.                                                |
 | `avispa.ecm.configuration.overwrite` | `true` if the existing configuration should be overwritten                                                                        |
 | `avispa.ecm.office.home`             | Home location to LibreOffice. `C:\Program Files\LibreOffice` by default.                                                          |
 
-## Rendition generating
+## Types and objects
+
+Each document or configuration which is stored in the database has a _type_ assigned to it. This type has to be
+registered in special `TYPE` database table. This type contains type name (reused `OBJECT_NAME` column) and Java class 
+name which corresponds to the registered type. Class name has to be a unique value. The type can be persisted in the 
+database in form of an _objects_. Avispa ECM considers types name as case-insensitive.
+
+### Objects hierarchy
+
+The root of all objects is `ECM_ENTITY` table. It later divides to `ECM_CONFIG` and `ECM_OBJECT`. Latter one is
+designated for objects related to [zip configuration](#zip-configuration) while former is a base for all other types.
+
+None of the three mentioned tables are not registered in `TYPE` table what means they are not designated to exist as
+independent objects. An actual type is represented by `DOCUMENT` table. Documents inherits from ECM objects and can be
+used as independent objects within the ECM solution.
+
+Full object metadata is a join of all tables tracked down to `ECM_ENTITY` table. For example for Document type, its 
+metadata will be in `DOCUMENT`, `ECM_OBJECT` and `ECM_ENTITY` tables identified by common UUID.
+
+### Objects contents
+
+Any object can have a _content_ file assigned to it. The file is stored in a _repository_, which is a special
+folder in the OS configured in the properties file. Details about object content are stored in the `CONTENT` table and
+are represented by `Content` type.
+
+### Discriminators
+
+Discriminators are a special columns marked on entity definition by `@TypeDiscriminator` annotation. They can serve as
+a column allowing to distinct between some categories of subtypes, which are not "physical" types registered in `TYPE`
+table. For example, we'd like to distinct between retail or customer client, but we want to store the data of both 
+within single database table.
+
+### Rendition generating
 
 Rendition is the source document converted to different format (for instance `.docx` to `.odt`).
 In this ECM context it is always conversion from any format supported by `JODConverter` library to PDF.
@@ -54,18 +92,54 @@ Avispa ECM is designed for easy customization for specific needs. It has 3 level
    conditions or how they should be managed.
 
 The last level is designated for the end-users. It allows to configure following aspects of ECM:
+
 - **Autolink** - rules telling to which logical folder the document should be linked after creation
 - **Autoname** - rules telling what should be the name of the document withing the ECM
 - **Dictionary** - dictionary is used in property pages for selecting only purposed values
 - **Property page** - definition of insert or update form used by GUI applications (like ECM Application)
-- **Template** - template document used by the customizations. It can be used for example to generate invoices, brochures or reports with fixed structure.
+- **Template** - template document used by the customizations. It can be used for example to generate invoices,
+  brochures or reports with fixed structure.
 - **Upsert** - configuration item telling, which property page should be used when inserting or updating document
 
-All documents in ECM are of `Document` type. It is possible to extend it to create more specific types with additional properties.
-These types and their properties can be used to link with different properties. It is done using **Context** configuration
-item, which defines kind of a configuration matrix telling, for which kind of documents configuration items should be triggered.
-This enables for example using different naming conventions or templates for different documents types. Documents applicable
-for a context are defined as a *match rule* using Conditions.
+All documents in ECM are of `Document` type. It is possible to extend it to create more specific types with additional
+properties. These types and their properties can be used to link with different properties. It is done using **Context**
+configuration item, which defines kind of a configuration matrix telling, for which kind of documents configuration 
+items should be triggered. This enables for example using different naming conventions or templates for different 
+documents types. Documents applicable for a context are defined as a _match rule_ using Conditions.
+
+### Dictionary
+
+_Dictionaries__ are key-value maps for storing expected values for objects fields. They can be later used for example on
+the UI as options for combo or radio boxes. The key is called a _label_ while value is a map of columns and their 
+respective values. It means single dictionary value can keep multiple values in fact. For example if we want to use 
+dictionary to store VAT rates the label will look like `VAT_08` and the value can contain `multiplier` column with 
+`0.08` value and `description` column with some additional explanation about the purpose of the value.
+
+Dictionary can be linked to the object field by annotating it with `@Dictionary` annotation and providing dictionary
+name.
+
+### Property page
+
+Property page is used to define the layout of UI form for displaying object fields (known also as _properties_).
+Property page configuration requires a JSON content file with the layout details. Object fields are wrapped in so-called
+_property controls_. There are also different kind of _controls_ which are not related to properties
+like `separator`, `label` or _grouping controls_ like `group`, `columns`, `table` or `tabs`. The file structure is 
+defined in JSON Schema files found [here](src/main/resources/json-schemas).
+
+Apart from controls defined in `table`, property controls can have a `required` property defined, which tells if the
+value of property must be provided or is optional.
+
+Additionally, all controls apart from `table` nested properties and `columns` can have a visibility and requirement
+conditions defined. See more about [conditions](#conditions). Visibility condition tells the control should be hidden.
+Requirement conditions overwrites `required` property if specified.
+
+Below are some of the general details about grouping limitations:
+
+- `columns` can have up to 4 nested controls, which are not a grouping controls.
+- `table` can use only `combo`, `date`, `datetime`, `money`, `number`, and `text` controls. Conditions are not allowed
+  for these controls, and they are always required. Tables cannot be present in any grouping control.
+- `group` does not allow to nest another group within it. However `columns` or `tabs` are allowed.
+- `tabs` allows to nest `columns` and `groups` without `tabs` nested.
 
 ## Conditions processing
 

lombok.config

@@ -0,0 +1 @@
+lombok.addLombokGeneratedAnnotation = true