From 4002c01134940b824af4f701484b6d010ef55eb8 Mon Sep 17 00:00:00 2001 From: Jose Luis Osorno Date: Tue, 15 Jan 2019 14:00:18 +0100 Subject: [PATCH] Documentation - Project structures Add articles to explain the SDK maven archetypes and the structure of the projects generated with them. --- docs/mvn-archetypes.md | 132 ++++++++++++++++++++ docs/projects-usage.md | 16 ++- docs/structure-aio.md | 246 +++++++++++++++++++++++++++++++++++++ docs/structure-platform.md | 0 docs/structure-share.md | 0 5 files changed, 392 insertions(+), 2 deletions(-) create mode 100644 docs/mvn-archetypes.md create mode 100644 docs/structure-aio.md create mode 100644 docs/structure-platform.md create mode 100644 docs/structure-share.md diff --git a/docs/mvn-archetypes.md b/docs/mvn-archetypes.md new file mode 100644 index 00000000..34d3e0a4 --- /dev/null +++ b/docs/mvn-archetypes.md @@ -0,0 +1,132 @@ +--- +Title: Alfresco SDK Maven archetypes +Added: v2.1.1 +Last reviewed: 2019-01-15 +--- +# Alfresco SDK Maven archetypes + +The Alfresco SDK 4.0 comes with a number of Maven archetypes that can be used to generate Alfresco extension projects. + +For more details, see [Getting started with Alfresco SDK 4.0](getting-started.md). + +These archetypes are available during the creation of a brand new project. In short, a [Maven archetype](https://maven.apache.org/guides/introduction/introduction-to-archetypes.html) +is a project templating toolkit. It's defined as an original pattern or model from which all other things of the same kind are made. Using archetypes +provides a great way to enable developers to quickly follow best practice in a consistent way. This is valid for every project built with Apache Maven and +it's valid in particular when using Alfresco SDK 4.0. + +In this section we are going to introduce all the available archetypes in Alfresco SDK 4.0, with a brief description of their purpose and main use. +After reading this information, you should be able to understand the various possibilities that Alfresco SDK 4.0 can offer to developers, in terms of +projects. + +When generating your project, you'll be prompted to select the Maven archetype you want to use through an interactive menu, similar to what you can see below. + +``` +[INFO] Generating project in Interactive mode +[INFO] No archetype defined. Using maven-archetype-quickstart (org.apache.maven.ar +chetypes:maven-archetype-quickstart:1.0) +Choose archetype: +1: remote -> org.alfresco.maven.archetype:activiti-jar-archetype (Sample project w +ith full support for lifecycle and rapid development of Activiti JARs) +2: remote -> org.alfresco.maven.archetype:alfresco-allinone-archetype (Sample mult +i-module project for All-in-One development on the Alfresco platform. Includes mod +ules for Platform/Repository JAR and Share JAR) +3: remote -> org.alfresco.maven.archetype:alfresco-amp-archetype (Sample project w +ith full support for lifecycle and rapid development of Repository AMPs (Alfresco +Module Packages)) +4: remote -> org.alfresco.maven.archetype:alfresco-platform-jar-archetype (Sample +project with full support for lifecycle and rapid development of Platform/Reposit +ory JARs and AMPs (Alfresco Module Packages)) +5: remote -> org.alfresco.maven.archetype:alfresco-share-jar-archetype (Share pro +ject with full support for lifecycle and rapid development of JARs and AMPs (Alfr +esco Module +Packages)) +6: remote -> org.alfresco.maven.archetype:share-amp-archetype (Share project with +full support for lifecycle and rapid development of AMPs (Alfresco Module +Packages)) +Choose a number or apply filter (format: [groupId:]artifactId, case sensitive con +tains): : +``` + +The menu shows 6 possible options, where each option corresponds to a different Maven archetype that you can select by using the listed numbers. +Please note that the numbering is not sequential and some numbers may be skipped. + +## Existing archetypes + +### org.alfresco.maven.archetype:alfresco-allinone-archetype + +This archetype allows a developer to implement the All-In-One project on Alfresco Content Services. The All-In-One project (also called AIO) is provided in +this and previous versions of Alfresco SDK, but in SDK 4.0 it has been reshaped to leverage on Docker. + +The All-In-One archetype allows a developer to create a multi-module project on Alfresco Content Services. The All-In-One project mainly includes a module for +the core repository in ACS and a module for the Share client. This includes: + +* ACS Repository JAR +* Alfresco Share JAR +* ACS Repository Docker image configuration +* Alfresco Share Docker image configuration +* Integration tests +* Docker containers (ACS, Share, Alfresco Search Service, PostgreSQL) configuration and orchestration via Docker compose +* (Optional) AMP deployment configuration (JAR is the recommended artifact type and the default) + +The project created using the All-In-One Maven archetype includes some sample code (by default) to show you how to develop with the Alfresco Content Services +Repository and the Alfresco Share client. The samples included in the project are basic and straightforward, and can help you to take the first steps into +Alfresco development. + +The All-In-One project is recommended to be used if you have to develop a customization of the Alfresco Content Services Repository together with +customizations on Alfresco Share client. If your plan to develop a project on the Alfresco Content Services Repository only, use the Platform JAR Maven +archetype. If you plan to develop a project on the Alfresco Share client only, use the Share JAR Maven archetype. + +For more information about the All-In-One project, see All-In-One project structure. **TODO**: Include link + +### org.alfresco.maven.archetype:alfresco-platform-jar-archetype + +This archetype allows a developer to implement the Platform JAR project on Alfresco Content Services. It has been reshaped in SDK 4.0 to leverage on Docker. + +The Platform JAR Maven archetype allows a developer to create a module on Alfresco Content Services, in particular on the Repository side, and includes: + +* ACS Repository JAR +* ACS Repository Docker image configuration +* Docker containers (ACS, Share (optional), Alfresco Search Service, PostgreSQL) configuration and orchestration via Docker compose +* (Optional) AMP deployment configuration (JAR is the recommended artifact type and the default) + +The project created using the Platform JAR Maven archetype includes some sample code (by default) to show you how to develop with the Alfresco Content +Services Repository. The samples included in the project are basic and straightforward, and can help you to take the first steps into Alfresco development. + +The Platform JAR project is recommended to be used if you have to develop a customization of the Alfresco Content Services Repository. If you also plan to +develop a customization of the Alfresco Share client, use the All-In-One Maven archetype instead. + +For more information about the Platform JAR project, see Platform JAR project structure. **TODO**: Include link + +### org.alfresco.maven.archetype:alfresco-share-jar-archetype + +This archetype allows a developer to implement the Share JAR project on an Alfresco Share client. It has been reshaped in SDK 4.0 to leverage on Docker. + +The Share JAR Maven archetype allows a developer to create a module on an Alfresco Share client, and includes: + +* Alfresco Share JAR +* Alfresco Share Docker image configuration +* Docker containers (ACS, Share, Alfresco Search Service, PostgreSQL) configuration and orchestration via Docker compose +* (Optional) AMP deployment configuration (JAR is the recommended artifact type and the default) + +The project created using the Share JAR Maven archetype includes some sample code (by default) to show you how to develop with the Alfresco Share client. +The samples included in the project are basic and straightforward, and can help you to take the first steps into Alfresco development. + +The Share JAR project is recommended to be used if you have to develop a customization of the Alfresco Share client. If you also plan to develop a +customization of the Alfresco Content Services Repository, use the All-In-One Maven archetype instead. + +For more information about the Share JAR project, see Share JAR project structure. **TODO**: Include link + +### org.alfresco.maven.archetype:activiti-jar-archetype (for use with SDK 2.2 only) + +This Maven archetype is related to an older version of the Alfresco SDK and should not be used. For technical reasons this archetype can't be hidden and is +still listed. + +### org.alfresco.maven.archetype:alfresco-amp-archetype (for use with SDK 2.2 only) + +This Maven archetype is related to an older version of the Alfresco SDK and should not be used. For technical reasons this archetype can't be hidden and is +still listed. + +### org.alfresco.maven.archetype:share-amp-archetype (for use with SDK 2.2 only) + +This Maven archetype is related to an older version of the Alfresco SDK and should not be used. For technical reasons this archetype can't be hidden and is +still listed. diff --git a/docs/projects-usage.md b/docs/projects-usage.md index 2182046e..79a94d30 100644 --- a/docs/projects-usage.md +++ b/docs/projects-usage.md @@ -1,7 +1,7 @@ --- Title: Working with generated projects Added: v3.0.0 -Last reviewed: 2019-01-14 +Last reviewed: 2019-01-15 --- # Working with generated projects @@ -14,6 +14,19 @@ local environment making an intensive use of Docker and Docker compose technolog If you're not familiar to these technologies, it is highly recommended visiting the [Docker documentation website](https://docs.docker.com). This site offers a great quantity of training resources about [Docker](https://docs.docker.com/get-started/) and [Docker compose](https://docs.docker.com/compose/gettingstarted/). +## Project structures + +After generating your project, using one of the Maven archetypes, review the project structure. The directory structure and content of each folder and file +can help you to understand how to start developing with the Alfresco SDK 4.0. Before continuing, make sure that have read and completed the tasks in the +[Getting started](getting-started.md) tutorial. + +The structure of the project and the purpose of the files it contains vary according to the [Maven archetype](mvn-archetypes.md) used to generate the project +itself. The following links provide detailed descriptions of the different project types. + +* [All-In-One project structure](structure-aio.md) +* [Platform JAR project structure](structure-platform.md) +* [Share JAR project structure](structure-share.md) + ## Run script All the projects generated using the Alfresco SDK 4.0 archetypes provide an utility script to work with the project. This script is `run.sh` for Unix systems @@ -38,4 +51,3 @@ configured them properly to be accessible in the path. In the case of Maven, it is not necessary that the `mvn` executable is in the path if you've properly configured the environment variable `M2_HOME`. The script looks for the `M2_HOME` environment variable to build the path to the `mvn` executable. - diff --git a/docs/structure-aio.md b/docs/structure-aio.md new file mode 100644 index 00000000..2d8ca1cc --- /dev/null +++ b/docs/structure-aio.md @@ -0,0 +1,246 @@ +--- +Title: All-In-One project structure +Added: v3.0.0 +Last reviewed: 2019-01-15 +--- +# All-In-One project structure + +The following pages provide a detailed description of the All-In-One (AIO) project, including the project structure and folder contents. + +Now that you know what an All-In-One project is, let’s introduce the structure of the project, once it is created using the +`org.alfresco.maven.archetype:alfresco-allinone-archetype`. + +Below is an example directory structure of an All-In-One project created with `com.example` as `groupId` and `my-all-in-one-project` as `artifactId`. + +``` +my-all-in-one-project +├── pom.xml +├── README.md +├── run.bat +├── run.sh +├── docker +| └── docker-compose.yml +├── integration-tests +| ├── pom.xml +│ └── src +│ ├── main +│ │ └── java +│ │ └── com +│ │ └── example +│ └── test +│ └── java +│ └── com +│ └── example +│ └── platformsample +│ ├── CustomContentModelIT.java +│ ├── DemoComponentIT.java +│ └── HelloWorldWebScriptIT.java +├── my-all-in-one-project-platform-docker +| ├── pom.xml +│ └── src +│ └── main +│ └── docker +│ ├── alfresco-global.properties +│ ├── dev-log4j.properties +│ ├── disable-webscript-caching-context.xml +│ ├── Dockerfile +│ ├── hotswap-agent.properties +│ └── license +│ └── README.md +├── my-all-in-one-project-platform-jar +│ ├── pom.xml +│ └── src +│ ├── main +│ │ ├── assembly +│ │ │ ├── amp.xml +│ │ │ ├── file-mapping.properties +│ │ │ └── web +│ │ │ └── README.md +│ │ ├── java +│ │ │ └── com +│ │ │ └── example +│ │ │ └── platformsample +│ │ │ ├── DemoComponent.java +│ │ │ ├── Demo.java +│ │ │ └── HelloWorldWebScript.java +│ │ └── resources +│ │ ├── alfresco +│ │ │ ├── extension +│ │ │ │ └── templates +│ │ │ │ └── webscripts +│ │ │ │ └── alfresco +│ │ │ │ └── tutorials +│ │ │ │ ├── helloworld.get.desc.xml +│ │ │ │ ├── helloworld.get.html.ftl +│ │ │ │ └── helloworld.get.js +│ │ │ └── module +│ │ │ └── my-all-in-one-project-platform-jar +│ │ │ ├── alfresco-global.properties +│ │ │ ├── context +│ │ │ │ ├── bootstrap-context.xml +│ │ │ │ ├── service-context.xml +│ │ │ │ └── webscript-context.xml +│ │ │ ├── messages +│ │ │ │ └── content-model.properties +│ │ │ ├── model +│ │ │ │ ├── content-model.xml +│ │ │ │ └── workflow-model.xml +│ │ │ ├── module-context.xml +│ │ │ ├── module.properties +│ │ │ └── workflow +│ │ │ └── sample-process.bpmn20.xml +│ │ └── META-INF +│ │ └── resources +│ │ └── test.html +│ └── test +│ └── java +│ └── com +│ └── example +│ └── platformsample +│ └── HelloWorldWebScriptControllerTest.java +├── my-all-in-one-project-share-docker +| ├── pom.xml +│ └── src +│ └── main +│ └── docker +│ ├── Dockerfile +│ ├── hotswap-agent.properties +│ ├── log4j.properties +│ └── share-config-custom.xml +└── my-all-in-one-project-share-jar + ├── pom.xml + └── src + ├── main + │ ├── assembly + │ │ ├── amp.xml + │ │ ├── file-mapping.properties + │ │ └── web + │ │ └── README.md + │ ├── java + │ │ └── com + │ ├── alfresco + │ │ ├── module + │ │ │ └── my-all-in-one-project-share-jar + │ │ │ └── module.properties + │ │ └── web-extension + │ │ ├── messages + │ │ │ └── my-all-in-one-project-share-jar.properties + │ │ ├── my-all-in-one-project-share-jar-slingshot-application-context.xml + │ │ ├── site-data + │ │ │ └── extensions + │ │ │ └── my-all-in-one-project-share-jar-example-widgets.xml + │ │ └── site-webscripts + │ │ ├── com + │ │ │ └── example + │ │ │ └── pages + │ │ │ ├── simple-page.get.desc.xml + │ │ │ ├── simple-page.get.html.ftl + │ │ │ └── simple-page.get.js + │ │ └── org + │ │ └── alfresco + │ │ └── README.md + │ └── META-INF + │ ├── resources + │ │ └── my-all-in-one-project-share-jar + │ │ └── js + │ │ └── tutorials + │ │ └── widgets + │ │ ├── css + │ │ │ └── TemplateWidget.css + │ │ ├── i18n + │ │ │ └── TemplateWidget.properties + │ │ ├── templates + │ │ │ └── TemplateWidget.html + │ │ └── TemplateWidget.js + │ └── share-config-custom.xml + └── test + └── java + └── com + └── example +``` + +From a high level standpoint, we can describe the content of the project as follows: + +* `my-all-in-one-project` (the root of the project) contains the whole project. It can easily be pushed into a version control repository and/or an internet +hosting service like GitHub, SVN, CVS, etc. +* The files stored into the root of the project are mainly related to actions and commands (running, debugging, etc.), technical configuration (`pom.xml`), +and documentation (`README.md`). +* `integration-tests` contains a sub-project entirely dedicated to integration tests. +* `my-all-in-one-project-platform-docker` (typically named ``) contains a sub-project dedicated to the configuration of a custom +Docker image with the Alfresco Content Services Repository and the customization module `my-all-in-one-project-platform-jar` installed. +* `my-all-in-one-project-platform-jar` (typically named ``) contains a sub-project entirely dedicated to the customization of the +Alfresco Content Services Repository. +* `my-all-in-one-project-share-docker` (typically named ``) contains a sub-project dedicated to the configuration of a custom +Docker image with the Alfresco Share client and the customization module `my-all-in-one-project-share-jar` installed. +* `my-all-in-one-project-share-jar` (typically named ``) contains a sub-project entirely dedicated to the customization of the +Alfresco Share client. + +After this brief introduction of the All-In-One project, let’s focus on the content of the folders. + +## Project root + +Below is a description of the files in the root of the project (in this case, `my-all-in-one-project`). + +File | Description +--- | --- +`run` (`sh` and `bat`) | Utility script to work with the project (compile, run, test, show logs, etc.). For detailed information about it, check [Working with generated projects](projects-usage.md). +`pom.xml` | This XML file contains information about the project and configuration details used by Apache Maven to build the project. You can define all the configurations, parameters, and settings in this file for projects as well as for sub-projects. +`README.md` | File in Markdown format containing the documentation for the project. + +## my-all-in-one-project-platform-jar + +Below is a description of the content in the `my-all-in-one-project-platform-jar` (typically named ``) sub-project. This sub-project +contains the source code entirely dedicated to the customizing the Alfresco Content Services Repository. + +Content | Description +--- | --- +`pom.xml` | This XML file contains information about the project and configuration details used by Apache Maven to build the project. You can define all the configurations, parameters, and settings in this file even if it depends on the parent pom in the root folder. For the majority of use cases, settings and configurations are directly inherited from the parent pom, and this file can work in its default version. +`src/main/assembly` | In this folder you can find everything that's needed to fully control creating the AMP artifact in the platform project. The main file to check is `amp.xml`. +`src/main/java/...` | This folder contains the same content you can find in a regular Java project, i.e. the Java source code. Here you should put all the custom classes, interfaces, and Java source code in general. +`src/main/resources/alfresco/extension/templates/webscripts` | In this folder you can find the extensions to the REST API related to Web Scripts . Repository Web Scripts are defined in XML, JavaScript, and FreeMarker files. These are referred to as Data Web Scripts as they usually return JSON or XML. The default project contains a Hello World example. +`src/main/resources/alfresco/module/` | This folder contains all the configuration files and settings for the Alfresco platform module. Here you can find context files, the `alfresco-global.properties` file, Content Model examples, and Activiti workflow examples. +`src/main/resources/META-INF` | This folder hosts the content that will be placed in the `META-INF` folder of a standard Java web application. +`src/test/java/...` | This folder contains the same content you can find in a regular Java project, i.e. the Java source code for tests. Here you should put all the custom classes, interfaces, and Java source code related to tests. + +## my-all-in-one-project-platform-docker + +Below is a description of the content in the `my-all-in-one-project-platform-docker` (typically named ``) sub-project. This +sub-project contains the resources required to define a custom Docker image with the Alfresco Content Services Repository and the customization module +`my-all-in-one-project-platform-jar` installed. + +Content | Description +--- | --- +`pom.xml` | This XML file contains information about the project and configuration details used by Apache Maven to build the project. It adds the dependency to the `my-all-in-one-project-platform-jar` module and configures the `maven-dependency-plugin` to copy all the artifacts required in the Docker image into the folder `${project.build.directory}/extensions`. +`src/main/docker` | In this folder you can find everything that's needed to fully configure the custom ACS Docker image. +`src/main/docker/Dockerfile` | This is the file that define the custom ACS Docker image. The default configuration installs all the existing JARs and AMPs under `${project.build.directory}/extensions` folder and adds custom configuration and license files. +`src/main/docker/license` | This folder contains the licenses required for running an Enterprise project. + +## my-all-in-one-project-share-jar + +Below is a description of the content in the `my-all-in-one-project-share-jar` (typically named ``) sub-project. This sub-project +contains the source code entirely dedicated to the customizing the Alfresco Share client. + +Content | Description +--- | --- +`pom.xml` | This XML file contains information about the project and configuration details used by Apache Maven to build the project. You can define all the configurations, parameters, and settings in this file even if it depends on the parent pom in the root folder. For the majority of use cases, settings and configurations are directly inherited from the parent pom, and this file can work in its default version. +`src/main/assembly` | In this folder you can find everything that's needed to fully control creating the AMP artifact in the platform project. The main file to check is `amp.xml`. +`src/main/java/...` | This folder contains the same content you can find in a regular Java project, i.e. the Java source code. Here you should put all the custom classes, interfaces, and Java source code in general. +`src/main/resources/alfresco/module/` | This folder contains all the configuration files and settings for the Alfresco Share module. Here you can find the property file for the module. +`src/main/resources/alfresco/web-extension` | In this folder you can find the extensions to the web client (Alfresco Share) and it's where you store Spring configurations that extend and override the system Share configuration. There are two important sub-directories here: `site-data` and `site-webscripts`. +`src/main/resources/alfresco/META-INF/resources` | This folder hosts the content that will be placed in the `META-INF` folder of a standard Java web application. It is best practice to use a further subdirectory based on the module name. This allows you to manage multiple modules, so that their web resources don't conflict with each other. +`src/main/resources/alfresco/ META-INF/share-config-custom.xml` | This file is a relevant Alfresco Share file used to configure the sub-project with the correct settings, depending on your environment. For more details, see [Share configuration](http://docs.alfresco.com/5.2/concepts/dev-extensions-share-configuration.html). + + +## my-all-in-one-project-share-docker + +Below is a description of the content in the `my-all-in-one-project-share-docker` (typically named ``) sub-project. This +sub-project contains the resources required to define a custom Docker image with the Alfresco Share Client and the customization module +`my-all-in-one-project-share-jar` installed. + +Content | Description +--- | --- +`pom.xml` | This XML file contains information about the project and configuration details used by Apache Maven to build the project. It adds the dependency to the `my-all-in-one-project-share-jar` module and configures the `maven-dependency-plugin` to copy all the artifacts required in the Docker image into the folder `${project.build.directory}/extensions`. +`src/main/docker` | In this folder you can find everything that's needed to fully configure the custom Alfresco Share Docker image. +`src/main/docker/Dockerfile` | This is the file that define the custom Alfresco Share Docker image. The default configuration installs all the existing JARs and AMPs under `${project.build.directory}/extensions` folder and adds custom configuration files. + + diff --git a/docs/structure-platform.md b/docs/structure-platform.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/structure-share.md b/docs/structure-share.md new file mode 100644 index 00000000..e69de29b