mirror of
https://github.com/Alfresco/alfresco-sdk.git
synced 2025-05-26 17:25:11 +00:00
Merge pull request #532 from Alfresco/sdk-4/documentation-update
Documentation - SDK 4 Documentation
This commit is contained in:
Jose Luis Osorno
GitHub
commit
5b21775793
19
README.md
19
README.md
@ -1,6 +1,8 @@
|
||||
# [](#features) Alfresco SDK
|
||||
|
||||
This is the home of the Alfresco SDK. The Alfresco SDK is used by developers to build extensions for the Alfresco Digital Business Platform. It is based on [Apache Maven](http://maven.apache.org/), compatible with major IDEs and enables Rapid Application Development (RAD) and Test Driven Development (TDD).
|
||||
This is the home of the Alfresco SDK. The Alfresco SDK is used by developers to build extensions for the Alfresco Digital Business Platform. It is based on
|
||||
[Apache Maven](http://maven.apache.org/), compatible with major IDEs and enables [Rapid Application Development (RAD)](https://en.wikipedia.org/wiki/Rapid_application_development)
|
||||
and [Test Driven Development (TDD)](https://en.wikipedia.org/wiki/Test-driven_development).
|
||||
|
||||
## License
|
||||
This project is released under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.html) license.
|
||||
@ -8,6 +10,7 @@ If you are an Enterprise customer check the [Support](#alfresco-enterprise-custo
|
||||
|
||||
## News
|
||||
|
||||
- 2019-XX-XX: Alfresco SDK 4.0.0 released **(confirmation required)**
|
||||
- 2017-06-23: Alfresco SDK 3.0.1 released, [containing a critical bugfix](https://github.com/Alfresco/alfresco-sdk/issues/461)
|
||||
- 2017-04-01: Alfresco SDK 3.0.0 released
|
||||
- 2017-03-27: After years of hard work, countless iterations and gathering feedback, SDK 3.0 has finally been merged into the master branch, ready for release in the coming days
|
||||
@ -21,11 +24,12 @@ If you are an Enterprise customer check the [Support](#alfresco-enterprise-custo
|
||||
## User Getting Started
|
||||
|
||||
### Latest Documentation
|
||||
To get started with **Alfresco SDK 4.0.x** (latest) visit the [Alfresco Documentation](https://docs.alfresco.com/6.0/concepts/dev-for-developers.html) (documentation pending).
|
||||
To get started with **Alfresco SDK 4.0.x** (latest) visit the [Alfresco Documentation](docs/README.md).
|
||||
|
||||
#### Documentation about Previous Versions
|
||||
| SDK Version | Alfresco Enterprise Version | Alfresco Community Version | Documentation |
|
||||
| ------------- |:-------------:| :-----:|:-----|
|
||||
| SDK 4.0 | Alfresco 6.0.x / 6.1.x | Alfresco 6.0.x / 6.1.x | https://master--alfresco-builder-network.netlify.com **(confirmation required)** |
|
||||
| SDK 3.0 | Alfresco 5.2.x | Alfresco 5.2.x | http://docs.alfresco.com/5.2/concepts/sdk-intro.html |
|
||||
| SDK 2.2 | Alfresco 5.1.x | Alfresco 5.1.x | https://docs.alfresco.com/5.1/concepts/alfresco-sdk-intro.html |
|
||||
| SDK 2.1 | Alfresco 5.0.1 | Alfresco 5.0.d | https://docs.alfresco.com/sdk2.1/concepts/alfresco-sdk-intro.html |
|
||||
@ -43,12 +47,13 @@ please check the [SDK Support status](http://www.alfresco.com/services/subscript
|
||||
for the version you are using. If your version is in Limited or Full Support and you need help, visit the [Support Portal](http://support.alfresco.com).
|
||||
|
||||
## Maven repositories
|
||||
- As of version 2.0-beta-1, The Alfresco SDK is released in [Maven Central](http://search.maven.org/#search|ga|1|alfresco-sdk). Previous versions are available in the [Alfresco Artifacts Repository](https://artifacts.alfresco.com/).
|
||||
- As of version 2.0-beta-1, The Alfresco SDK is released in [Maven Central](http://search.maven.org/#search|ga|1|alfresco-sdk). Previous versions are available
|
||||
in the [Alfresco Artifacts Repository](https://artifacts.alfresco.com/).
|
||||
- Alfresco (Community and Enterprise) artifacts are hosted in the [Alfresco Artifacts Repository](https://artifacts.alfresco.com/).
|
||||
- Alfresco Community artifacts (JARs, WARs, AMPs, poms) and SDK artifacts are publicly available.
|
||||
|
||||
*NOTE:* By default the Alfresco SDK will use Community Edition releases but it can be configured to use Enterprise Edition releases. Enterprise and Premier customers can use the SDK with
|
||||
Enterprise Edition releases by following the process described in [Working with Enterprise](https://docs.alfresco.com/5.2/concepts/sdk-using-enterprise.html)
|
||||
*NOTE:* By default the Alfresco SDK will use Community Edition releases but it can be configured to use Enterprise Edition releases. Enterprise and Premier
|
||||
customers can use the SDK with Enterprise Edition releases by following the process described in [Working with Enterprise](docs/advanced-topics/working-with-enterprise/README.md).
|
||||
|
||||
### Alfresco Artifacts Repository
|
||||
|
||||
@ -72,5 +77,9 @@ To test new unreleased (unsupported) features, you can use the following snippet
|
||||
</repository>
|
||||
```
|
||||
|
||||
## Docker registries
|
||||
- Alfresco Community Docker images are publicly available at the [Alfresco's Docker Hub profile](https://hub.docker.com/u/alfresco/).
|
||||
- Alfresco Enterprise Docker images are hosted at [Quay.io](https://quay.io/). Its configuration process is described in detail in [How to configure private Alfresco Docker registry](docs/advanced-topics/working-with-enterprise/enterprise-docker-registry.md).
|
||||
|
||||
## For Developers that want to contribute to the SDK
|
||||
See the [Developers Wiki page](https://github.com/Alfresco/alfresco-sdk/wiki/Developer-Wiki).
|
||||
|
||||
57
docs/README.md
Normal file
57
docs/README.md
Normal file
@ -0,0 +1,57 @@
|
||||
---
|
||||
Title: Alfresco SDK 4.0
|
||||
Added: v3.0.0
|
||||
Last reviewed: 2019-01-17
|
||||
---
|
||||
# Alfresco SDK 4.0
|
||||
|
||||
Alfresco SDK 4.0 is a Maven based development kit that provides an easy to use approach to developing applications and extensions for Alfresco. With this
|
||||
SDK you can develop, package, test, run, document and release your Alfresco extension project.
|
||||
|
||||
For earlier releases of the Alfresco SDK, see the Previous versions section of [http://docs.alfresco.com](http://docs.alfresco.com).
|
||||
|
||||
The Alfresco Software Development Kit (Alfresco SDK) is a fundamental tool provided by Alfresco to developers to build customizations and extensions for
|
||||
the Alfresco Digital Business Platform. It is based on [Apache Maven](http://maven.apache.org/) and [Docker](https://www.docker.com/) and is compatible with
|
||||
major IDEs. This enables Rapid Application Development (RAD) and Test Driven Development (TDD).
|
||||
|
||||
Alfresco SDK 4.0 is released under [Apache License version 2.0](http://www.apache.org/licenses/LICENSE-2.0.html) and supports Alfresco Content Services both
|
||||
in Community Edition and Enterprise Edition. If you're an Enterprise customer, please check the [Alfresco SDK Support status](https://www.alfresco.com/alfresco-product-support-status)
|
||||
for the version you're using. If your version is in Limited or Full Support and you need help, contact our Support team [http://support.alfresco.com](http://support.alfresco.com/).
|
||||
|
||||
Alfresco SDK 4.0 is a major update to the SDK and provides several improvements on the previous releases.
|
||||
|
||||
The 4.0 release takes advantage of Semantic Versioning ([SEMVER](http://semver.org/)), which means that this new release is not directly compatible with the
|
||||
previous releases of the SDK.
|
||||
|
||||
If you have existing projects that you wish to upgrade to SDK 4.0.x, the recommended approach is to generate a new project from our archetypes and move your
|
||||
code into place.
|
||||
|
||||
## Documentation Content
|
||||
|
||||
* [What's new?](whats-new.md)
|
||||
* [Getting started with Alfresco SDK 4.0](getting-started.md)
|
||||
* [Alfresco SDK Maven archetypes](mvn-archetypes.md)
|
||||
* [Working with generated projects](working-with-generated-projects/README.md)
|
||||
* [All-In-One project structure](working-with-generated-projects/structure-aio.md)
|
||||
* [Platform JAR project structure](working-with-generated-projects/structure-platform.md)
|
||||
* [Share JAR project structure](working-with-generated-projects/structure-share.md)
|
||||
* [Setting up your development environment](setting-up-your-development-environment/README.md)
|
||||
* [Setting up your development environment using Eclipse](setting-up-your-development-environment/dev-env-eclipse.md)
|
||||
* [Setting up your development environment using Intellij IDEA](setting-up-your-development-environment/dev-env-intellij.md)
|
||||
* [Advanced topics](advanced-topics/README.md)
|
||||
* [Switching Alfresco Content Services and Share versions](advanced-topics/switching-versions.md)
|
||||
* [Working with Enterprise](advanced-topics/working-with-enterprise/README.md)
|
||||
* [How to configure private Alfresco Nexus repository](advanced-topics/working-with-enterprise/enterprise-mvn-repo.md)
|
||||
* [How to configure private Alfresco Docker registry](advanced-topics/working-with-enterprise/enterprise-docker-registry.md)
|
||||
* [How to set up Alfresco Transform Service](advanced-topics/working-with-enterprise/alfresco-transform-service.md)
|
||||
* [Working with AMPs](advanced-topics/amps.md)
|
||||
* [Debugging](advanced-topics/debugging/README.md)
|
||||
* [Remote debugging using Eclipse](advanced-topics/debugging/debug-eclipse.md)
|
||||
* [Remote debugging using IntelliJ](advanced-topics/debugging/debug-intellij.md)
|
||||
* [Integration testing](advanced-topics/integration-testing/README.md)
|
||||
* [How SDK's integration tests work](advanced-topics/integration-testing/it-working.md)
|
||||
* [How to run SDK's integration tests](advanced-topics/integration-testing/it-running.md)
|
||||
* [Hot reloading](advanced-topics/hot-reloading/README.md)
|
||||
* [How to configure and use JRebel](advanced-topics/hot-reloading/jrebel.md)
|
||||
* [How to configure and use Hotswap Agent](advanced-topics/hot-reloading/hotswap-agent.md)
|
||||
* [Troubleshooting](troubleshooting.md)
|
||||
9
docs/advanced-topics/README.md
Normal file
9
docs/advanced-topics/README.md
Normal file
@ -0,0 +1,9 @@
|
||||
---
|
||||
Title: Advanced topics
|
||||
Added: v3.0.0
|
||||
Last reviewed: 2019-01-17
|
||||
---
|
||||
# Advanced topics
|
||||
|
||||
This information provides more advanced topics that you might come in contact with when you have been working with an SDK project for a while. We will have a
|
||||
look at how you can work with AMPs, remote debugging, hot reloading, and more.
|
||||
243
docs/advanced-topics/amps.md
Normal file
243
docs/advanced-topics/amps.md
Normal file
@ -0,0 +1,243 @@
|
||||
---
|
||||
Title: Working with AMPs
|
||||
Added: v3.0.0
|
||||
Last reviewed: 2019-01-14
|
||||
---
|
||||
# Working with AMPs
|
||||
|
||||
Since the early days of the Alfresco SDK, the Alfresco Module Packages (AMP) have been the way customizations were packaged. In Alfresco SDK 4.0 everything
|
||||
is packaged as a JAR by default, while the AMPs are still available as an optional assembly. This gives you much more control over packaging, and simple
|
||||
modules can easily be deployed as JARs.
|
||||
|
||||
The [Maven Assembly Plugin](http://maven.apache.org/plugins/maven-assembly-plugin/) allows you to control the final artifacts that Maven builds. You add the
|
||||
plugin configuration and point it to an XML file that contains the full configuration on the artifact we want to produce.
|
||||
|
||||
## Building AMPs with Alfresco SDK 4
|
||||
|
||||
To build AMPs the SDK ships a default assembly XML file that will tell the assembly plugin how to produce an AMP file. You will find this file in
|
||||
`src/main/assembly/amp.xml` (in the case of All-In-One project you'll find one descriptor for the platform JAR module and another for the share JAR module).
|
||||
The plugin configuration is already present in your `pom.xml` file, as shown:
|
||||
|
||||
```
|
||||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-assembly-plugin</artifactId>
|
||||
<version>2.6</version>
|
||||
<executions>
|
||||
<execution>
|
||||
<id>build-amp-file</id>
|
||||
<phase>package</phase>
|
||||
<goals>
|
||||
<goal>single</goal>
|
||||
</goals>
|
||||
<configuration>
|
||||
<appendAssemblyId>false</appendAssemblyId>
|
||||
<descriptor>src/main/assembly/amp.xml</descriptor>
|
||||
</configuration>
|
||||
</execution>
|
||||
</executions>
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>org.alfresco.maven.plugin</groupId>
|
||||
<artifactId>alfresco-maven-plugin</artifactId>
|
||||
<version>${alfresco.sdk.version}</version>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
</plugin>
|
||||
```
|
||||
|
||||
This section is commented out by default.
|
||||
|
||||
1. To produce both a JAR file and an AMP, remove the comments and run the `mvn package` command.
|
||||
|
||||
Now you have full control over how your AMPs are built. If you want to change the content of the AMP, you can change the assembly `amp.xml` and tailor it
|
||||
to your needs.
|
||||
|
||||
## Installing AMPs with the SDK
|
||||
|
||||
The projects created from the Alfresco SDK 4.0 archetypes are configured to deploy either JARs or AMPs to the ACS / Share docker container. The only thing to
|
||||
do is modify the `pom.xml` file of the corresponding docker module / project in order to properly configure the dependencies and the Maven dependency plugin.
|
||||
|
||||
### All-In-One project
|
||||
|
||||
1. Modify the platform JAR dependency from the file `PROJECT_ARTIFACT_ID-platform-docker/pom.xml` to set the type of dependency to `amp`:
|
||||
|
||||
```
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>org.alfresco</groupId>
|
||||
<artifactId>sample-module-platform-jar</artifactId>
|
||||
<version>1.0-SNAPSHOT</version>
|
||||
<type>amp</type>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
```
|
||||
|
||||
2. Modify the Maven Dependency Plugin in the file `PROJECT_ARTIFACT_ID-platform-docker/pom.xml` to set the platform JAR dependency type to `amp`:
|
||||
|
||||
```
|
||||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-dependency-plugin</artifactId>
|
||||
<executions>
|
||||
<!-- Copy the repository extension and the dependencies required for execute integration tests -->
|
||||
<execution>
|
||||
<id>copy-repo-extension</id>
|
||||
<phase>pre-integration-test</phase>
|
||||
<goals>
|
||||
<goal>copy</goal>
|
||||
</goals>
|
||||
<configuration>
|
||||
<artifactItems>
|
||||
<artifactItem>
|
||||
<groupId>org.alfresco</groupId>
|
||||
<artifactId>sample-module-platform-jar</artifactId>
|
||||
<version>1.0-SNAPSHOT</version>
|
||||
<overWrite>false</overWrite>
|
||||
<outputDirectory>${project.build.directory}/extensions</outputDirectory>
|
||||
<type>amp</type>
|
||||
</artifactItem>
|
||||
<!-- Test dependencies -->
|
||||
...
|
||||
</artifactItems>
|
||||
</configuration>
|
||||
</execution>
|
||||
<!-- Copy other dependencies (JARs or AMPs) declared in the platform module -->
|
||||
...
|
||||
</executions>
|
||||
</plugin>
|
||||
```
|
||||
|
||||
3. Repeat these steps for the share module in the file `PROJECT_ARTIFACT_ID-share-docker/pom.xml`.
|
||||
|
||||
### Platform / Share project
|
||||
|
||||
1. Modify the Maven Dependency Plugin in the file `pom.xml` to set the platform / share JAR dependency type to `amp`:
|
||||
|
||||
```
|
||||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-dependency-plugin</artifactId>
|
||||
<executions>
|
||||
<!-- Copy the repository extension and the dependencies required for execute integration tests -->
|
||||
<execution>
|
||||
<id>copy-repo-extension</id>
|
||||
<phase>pre-integration-test</phase>
|
||||
<goals>
|
||||
<goal>copy</goal>
|
||||
</goals>
|
||||
<configuration>
|
||||
<artifactItems>
|
||||
<artifactItem>
|
||||
<groupId>org.alfresco</groupId>
|
||||
<artifactId>sample-platform-jar</artifactId>
|
||||
<version>1.0-SNAPSHOT</version>
|
||||
<overWrite>false</overWrite>
|
||||
<outputDirectory>${project.build.directory}/extensions</outputDirectory>
|
||||
<type>amp</type>
|
||||
</artifactItem>
|
||||
<!-- Test dependencies -->
|
||||
...
|
||||
</artifactItems>
|
||||
</configuration>
|
||||
</execution>
|
||||
<!-- Copy other dependencies (JARs or AMPs) declared in the platform module -->
|
||||
...
|
||||
</executions>
|
||||
</plugin>
|
||||
```
|
||||
|
||||
Once this configuration is in place, you simply need to rebuild and restart the project. The new configuration will make the Docker images automatically
|
||||
install the packaged AMPs in ACS / Share.
|
||||
|
||||
## Installing 3rd party AMPs
|
||||
|
||||
Installing 3rd party AMPs to the projects is pretty simple. The only requirement is adding the dependency to the project. The default configuration installs
|
||||
any AMPs set as a maven dependency in the corresponding Docker image. It is important to remember that ACS and Share are separated containers, so you'll need
|
||||
to add the dependency in the corresponding docker module in case of an All-In-One project.
|
||||
|
||||
Here is an example of how to install Florian Maul's Javascript Console.
|
||||
|
||||
```
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0"
|
||||
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
<artifactId>sample-module-platform-docker</artifactId>
|
||||
<name>Alfresco Platform/Repository Docker Module</name>
|
||||
<description>Platform/Repo Docker Module to generate the final Docker image</description>
|
||||
<packaging>jar</packaging>
|
||||
|
||||
<parent>
|
||||
<groupId>org.alfresco</groupId>
|
||||
<artifactId>sample-module</artifactId>
|
||||
<version>1.0-SNAPSHOT</version>
|
||||
</parent>
|
||||
|
||||
<properties>
|
||||
</properties>
|
||||
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>org.alfresco</groupId>
|
||||
<artifactId>sample-module-platform-jar</artifactId>
|
||||
<version>1.0-SNAPSHOT</version>
|
||||
</dependency>
|
||||
|
||||
<!-- Javascript Console AMP -->
|
||||
<dependency>
|
||||
<groupId>de.fmaul</groupId>
|
||||
<artifactId>javascript-console-repo</artifactId>
|
||||
<version>0.6</version>
|
||||
<type>amp</type>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
|
||||
...
|
||||
</project>
|
||||
```
|
||||
|
||||
## Controlling the order AMPs are applied
|
||||
|
||||
Under some specific circumstances it is necessary to apply different AMPs in a development project in a precise order. The default configuration of the
|
||||
projects generated using the Alfresco SDK 4.0 archetypes doesn't specify any concrete order applying the AMPs to the ACS/Share installation.
|
||||
|
||||
Anyway, that order can be controlled modifying slightly the configuration of the custom Docker images in the project. For instance, let's say we have three
|
||||
third party AMPs that we want to apply in the next order `third-party-amp-01.amp -> third-party-amp-02.amp -> third-party-amp-03.amp`. In this example, we're
|
||||
going to consider we need to apply them to a platform JAR module (the process would be the same for a Share module, simply changing the path of the files).
|
||||
|
||||
1. Follow the steps described in the section [Installing 3rd party AMPs](#installing-3rd-party-amps) to include all the AMPs dependencies.
|
||||
|
||||
2. Locate the `Dockerfile` under the folder `src/main/docker`. In this file, there is a section that copies and applies the AMPs to the ACS installation.
|
||||
|
||||
```
|
||||
# Copy Dockerfile to avoid an error if no AMPs exist
|
||||
COPY Dockerfile extensions/*.amp $TOMCAT_DIR/amps/
|
||||
RUN java -jar $TOMCAT_DIR/alfresco-mmt/alfresco-mmt*.jar install \
|
||||
$TOMCAT_DIR/amps $TOMCAT_DIR/webapps/alfresco -directory -nobackup -force
|
||||
```
|
||||
|
||||
3. Replace the `RUN` command to execute one installation of AMP each time and copy it three times, ensuring the installation is executed in the required
|
||||
order:
|
||||
|
||||
```
|
||||
# Copy Dockerfile to avoid an error if no AMPs exist
|
||||
COPY Dockerfile extensions/*.amp $TOMCAT_DIR/amps/
|
||||
# Install third-party-amp-01
|
||||
RUN java -jar $TOMCAT_DIR/alfresco-mmt/alfresco-mmt*.jar install \
|
||||
$TOMCAT_DIR/amps/third-party-amp-01.amp $TOMCAT_DIR/webapps/alfresco -directory -nobackup -force
|
||||
# Install third-party-amp-02
|
||||
RUN java -jar $TOMCAT_DIR/alfresco-mmt/alfresco-mmt*.jar install \
|
||||
$TOMCAT_DIR/amps/third-party-amp-02.amp $TOMCAT_DIR/webapps/alfresco -directory -nobackup -force
|
||||
# Install third-party-amp-03
|
||||
RUN java -jar $TOMCAT_DIR/alfresco-mmt/alfresco-mmt*.jar install \
|
||||
$TOMCAT_DIR/amps/third-party-amp-03.amp $TOMCAT_DIR/webapps/alfresco -directory -nobackup -force
|
||||
```
|
||||
|
||||
4. Rebuild and restart the project (use `run.bat` instead in Windows):
|
||||
|
||||
```
|
||||
$ ./run.sh build_start
|
||||
```
|
||||
|
||||
At this point, you have configured your project to apply the AMPs in a specific order.
|
||||
13
docs/advanced-topics/debugging/README.md
Normal file
13
docs/advanced-topics/debugging/README.md
Normal file
@ -0,0 +1,13 @@
|
||||
---
|
||||
Title: Debugging
|
||||
Added: v3.0.0
|
||||
Last reviewed: 2019-01-17
|
||||
---
|
||||
# Debugging
|
||||
|
||||
When developing add-ins, fixing bugs, or changing Alfresco from the source code, it is helpful to debug an instance of Alfresco running on a standard
|
||||
application server. This section outlines the steps needed to configure Alfresco and Eclipse (or IntelliJ IDEA) to provide a real-time view of the server
|
||||
and to troubleshoot issues by stepping through the code line by line.
|
||||
|
||||
Here we assume you have already generated an Alfresco project using the Alfresco SDK. If you don't have a project already, follow the steps in
|
||||
[Getting started with Alfresco SDK 4.0](../../getting-started.md) to learn how to generate it in a few easy steps.
|
||||
100
docs/advanced-topics/debugging/debug-eclipse.md
Normal file
100
docs/advanced-topics/debugging/debug-eclipse.md
Normal file
@ -0,0 +1,100 @@
|
||||
---
|
||||
Title: Remote debugging using Eclipse
|
||||
Added: v3.0.0
|
||||
Last reviewed: 2019-01-14
|
||||
---
|
||||
# Remote debugging using Eclipse
|
||||
|
||||
All the projects generated using the Alfresco SDK 4.0 are pre-configured to listen for remote debug connections. Depending on the selected archetypes you'll
|
||||
have a port for remotely debugging ACS, share or both of them.
|
||||
|
||||
By default, the remote debug port for ACS is **8888** and for share is **9898**. This configuration can be changed through the maven properties `acs.debug.port`
|
||||
and `share.debug.port` in the `pom.xml` file of the main project.
|
||||
|
||||
```
|
||||
<!-- Environment configuration properties -->
|
||||
<share.port>8180</share.port>
|
||||
<share.debug.port>9898</share.debug.port>
|
||||
<acs.host>${artifactId}-acs</acs.host>
|
||||
<acs.port>8080</acs.port>
|
||||
<acs.debug.port>8888</acs.debug.port>
|
||||
```
|
||||
|
||||
These remote debug ports are configured in the docker compose file to be exposed by the corresponding docker containers.
|
||||
|
||||
```
|
||||
services:
|
||||
sample-project-share:
|
||||
...
|
||||
environment:
|
||||
CATALINA_OPTS: "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=0.0.0.0:8888"
|
||||
REPO_HOST: sample-project-acs
|
||||
REPO_PORT: 8080
|
||||
ports:
|
||||
- "${share.port}:8080"
|
||||
- "${share.debug.port}:8888"
|
||||
sample-project-acs:
|
||||
...
|
||||
environment:
|
||||
CATALINA_OPTS: "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=0.0.0.0:8888"
|
||||
ports:
|
||||
- "${acs.port}:8080"
|
||||
- "${acs.debug.port}:8888"
|
||||
...
|
||||
```
|
||||
|
||||
## Configuring remote debugging using Eclipse
|
||||
|
||||
Here you'll see how to create and manage a configuration to remotely debug your launched Alfresco project that's waiting for a connection. This assumes you
|
||||
have an Eclipse IDE up and running, and have already imported the same project you are going to debug.
|
||||
|
||||
For more details on how to import an Alfresco project into your Eclipse IDE, see Setting up your development environment using Eclipse.
|
||||
|
||||
1. Open the Eclipse IDE and click on `Run Configurations` (top right).
|
||||
|
||||
|
||||
|
||||
2. Click on the green plus sign (top left) and select `Remote Java Application` to add a new configuration for a remote app.
|
||||
|
||||
3. Enter a descriptive name for your configuration, for example, `Sample project ACS debug`.
|
||||
|
||||
|
||||
|
||||
4. Click Browse then locate the platform project JAR if you want to debug ACS or the share project JAR if you want to debug share.
|
||||
|
||||
5. Check that your settings match the screenshot. This is a sample to debug ACS. If you want to debug share or you have configured custom ports for remote
|
||||
debugging you'll need to modify that configuration. If you're working with _Docker Toolbox_ instead of _Docker Desktop_ the host to access the container won't
|
||||
be `localhost` but a configured _IP_ address (i.e. 192.168.99.100).
|
||||
|
||||
6. Click `Apply`.
|
||||
|
||||
You will be taken back to the project source code.
|
||||
|
||||
7. Click on the bug icon and select the new configuration to run it.
|
||||
|
||||
|
||||
|
||||
The IDE connects the source code to the deployed one at the docker container. Once the code is linked, you can open a browser and start using your
|
||||
application. In our case, we are going to test the behaviour of debugging by running the sample webscript.
|
||||
|
||||
8. Open your browser and type `http://localhost:8080/alfresco/s/sample/helloworld`.
|
||||
|
||||
This is a sample webscript generated in every project created using SDK 4.0 and the platform artifact.
|
||||
|
||||
|
||||
|
||||
Now let's find the `HelloWorldWebScript.java` file in the `src/main/java/.../platformsample` folder of your project. If you're using an All-In-One project,
|
||||
the folder is located in the platform sub-project.
|
||||
|
||||
9. Edit the file using Eclipse IDE and set a breakpoint (by clicking to the left of the line number) at line:
|
||||
|
||||
```
|
||||
model.put(“fromJava”,”HelloFromJava”);
|
||||
```
|
||||
|
||||
10. Refresh the browser. Eclipse will intercept the execution at the breakpoint:
|
||||
|
||||
|
||||
|
||||
From here the management is the same as for a regular Java application using your preferred IDE. Please note that the whole Alfresco source code is available
|
||||
at debug time, thanks to the local maven repository.
|
||||
98
docs/advanced-topics/debugging/debug-intellij.md
Normal file
98
docs/advanced-topics/debugging/debug-intellij.md
Normal file
@ -0,0 +1,98 @@
|
||||
---
|
||||
Title: Remote debugging using IntelliJ
|
||||
Added: v3.0.0
|
||||
Last reviewed: 2019-01-14
|
||||
---
|
||||
# Remote debugging using IntelliJ
|
||||
|
||||
All the projects generated using the Alfresco SDK 4.0 are pre-configured to listen for remote debug connections. Depending on the selected archetypes you'll
|
||||
have a port for remotely debugging ACS, share or both of them.
|
||||
|
||||
By default, the remote debug port for ACS is **8888** and for share is **9898**. This configuration can be changed through the maven properties `acs.debug.port`
|
||||
and `share.debug.port` in the `pom.xml` file of the main project.
|
||||
|
||||
```
|
||||
<!-- Environment configuration properties -->
|
||||
<share.port>8180</share.port>
|
||||
<share.debug.port>9898</share.debug.port>
|
||||
<acs.host>${artifactId}-acs</acs.host>
|
||||
<acs.port>8080</acs.port>
|
||||
<acs.debug.port>8888</acs.debug.port>
|
||||
```
|
||||
|
||||
These remote debug ports are configured in the docker compose file to be exposed by the corresponding docker containers.
|
||||
|
||||
```
|
||||
services:
|
||||
sample-project-share:
|
||||
...
|
||||
environment:
|
||||
CATALINA_OPTS: "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=0.0.0.0:8888"
|
||||
REPO_HOST: sample-project-acs
|
||||
REPO_PORT: 8080
|
||||
ports:
|
||||
- "${share.port}:8080"
|
||||
- "${share.debug.port}:8888"
|
||||
sample-project-acs:
|
||||
...
|
||||
environment:
|
||||
CATALINA_OPTS: "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=0.0.0.0:8888"
|
||||
ports:
|
||||
- "${acs.port}:8080"
|
||||
- "${acs.debug.port}:8888"
|
||||
...
|
||||
```
|
||||
|
||||
## Configuring remote debugging using IntelliJ
|
||||
|
||||
Here you'll see how to create and manage a configuration to remotely debug your launched Alfresco project that's waiting for a connection. This assumes you
|
||||
have an IntelliJ IDEA IDE up and running, and have already imported the same project you are going to debug.
|
||||
|
||||
For more details on how to import an Alfresco project into your IntelliJ IDEA IDE, see Setting up your development environment using Intellij IDEA.
|
||||
|
||||
1. Open the IntelliJ IDEA IDE and click on `Add/Edit Configurations` (top right).
|
||||
|
||||
|
||||
|
||||
2. Click on the plus icon (top left) and select `Remote` to add a new configuration for a remote app.
|
||||
|
||||
3. Enter a descriptive name for your configuration, for example, `Sample project ACS debug`.
|
||||
|
||||
|
||||
|
||||
4. Check that your settings match the screenshot. This is a sample to debug ACS. If you want to debug share or you have configured custom ports for remote
|
||||
debugging you'll need to modify that configuration. If you're working with _Docker Toolbox_ instead of _Docker Desktop_ the host to access the container won't
|
||||
be `localhost` but a configured _IP_ address (i.e. 192.168.99.100).
|
||||
|
||||
5. Click `OK`.
|
||||
|
||||
You will be taken back to the project source code.
|
||||
|
||||
6. Click on the `Edit Configurations` dropdown box and select the new configuration to run it.
|
||||
|
||||
|
||||
|
||||
The IDE connects the source code with the deployed one at the docker container. Once the code is linked, you can open a browser and start using your
|
||||
application. In our case, we are going to test the behaviour of debugging by running the sample webscript.
|
||||
|
||||
7. Open your browser and type `http://localhost:8080/alfresco/s/sample/helloworld`.
|
||||
|
||||
This is a sample webscript generated in every project created using SDK 4.0 and the platform artifact.
|
||||
|
||||
|
||||
|
||||
Now let's find the `HelloWorldWebScript.java` file in the `src/main/java/.../platformsample` folder of your project. If you're using an All-In-One project,
|
||||
the folder is located in the platform sub-project.
|
||||
|
||||
8. Edit the file using IntelliJ IDEA IDE and set a breakpoint (by clicking to the left of the line number) at line:
|
||||
|
||||
```
|
||||
model.put(“fromJava”,”HelloFromJava”);
|
||||
```
|
||||
|
||||
9. Refresh the browser. IntelliJ IDEA will intercept the execution at the breakpoint:
|
||||
|
||||
|
||||
|
||||
From here the management is the same as for a regular Java application using your preferred IDE. Please note that the whole Alfresco source code is available
|
||||
at debug time, thanks to the local maven repository.
|
||||
28
docs/advanced-topics/hot-reloading/README.md
Normal file
28
docs/advanced-topics/hot-reloading/README.md
Normal file
@ -0,0 +1,28 @@
|
||||
---
|
||||
Title: Hot reloading
|
||||
Added: v3.0.0
|
||||
Last reviewed: 2019-01-17
|
||||
---
|
||||
# Hot reloading
|
||||
|
||||
Hot reloading in a Java project is the ability to avoid the infamous _change > restart and wait > check_ development lifecycle. This allows you to modify
|
||||
your application's code, and view the changes without having to restart Alfresco Content Services / Alfresco Share. You can potentially gain significant
|
||||
savings in development time that would otherwise be wasted rebuilding the Docker images and restarting the Docker containers.
|
||||
|
||||
Hot reloading is a well known behaviour in several other languages (C# for example), and the most practical and fast lifecycle like Save&Reload should be
|
||||
possible. Hot reloading is the key to enabling [Rapid Application Development (RAD)](https://en.wikipedia.org/wiki/Rapid_application_development) and
|
||||
[Test Driven Development (TDD)](https://en.wikipedia.org/wiki/Test-driven_development).
|
||||
|
||||
Since the Java 1.4 JVM, the Debugger API allowed debuggers to update class bytecode in place, using the same class identity. This meant that all objects
|
||||
could refer to an updated class and execute new code when their methods were called, preventing the need to reload a container whenever class bytecode was
|
||||
changed. All modern IDEs support it, including Eclipse, IntelliJ IDEA, and NetBeans. Since Java 5, this functionality has also been available directly to
|
||||
Java applications through the [Instrumentation API](http://docs.oracle.com/javase/6/docs/technotes/guides/instrumentation/index.html).
|
||||
|
||||
In the Alfresco development lifecycle hot reloading is possible as in every other Java project (and with the same limitations). You can manage a project
|
||||
created with the Alfresco SDK using hot reloading through two different tools:
|
||||
* [JRebel](jrebel.md)
|
||||
* [HotSwapAgent](hotswap-agent.md)
|
||||
|
||||
Both have advantages and disadvantages, so it's up to you to make the right choice for your needs. [JRebel](https://zeroturnaround.com/software/jrebel/) is a
|
||||
commercial product while [HotSwapAgent](http://hotswapagent.org/index.html) is open source. Both products can reload classes and web resources. However,
|
||||
JRebel is more powerful than HotSwapAgent and can also reload changes to the Spring XML context files, for example.
|
||||
285
docs/advanced-topics/hot-reloading/hotswap-agent.md
Normal file
285
docs/advanced-topics/hot-reloading/hotswap-agent.md
Normal file
@ -0,0 +1,285 @@
|
||||
---
|
||||
Title: How to configure and use Hotswap Agent
|
||||
Added: v3.0.0
|
||||
Last reviewed: 2019-01-14
|
||||
---
|
||||
# How to configure and use Hotswap Agent
|
||||
|
||||
[HotSwapAgent](http://hotswapagent.org/index.html) is the agent that enables you to do hot reloading. This allows you to modify the application code, and
|
||||
view the changes without having to restart Alfresco Tomcat (or the ACS Docker container).
|
||||
|
||||
A prerequisite for this tutorial is to have a project created with the Alfresco SDK 4.0, using the All-In-One archetype or the Platform JAR archetype. It's
|
||||
worth noting that hot reloading is only supported on the platform, and not in Alfresco Share.
|
||||
|
||||
As an alternative to the HotSwapAgent you can also try out JRebel. It has more features but isn't free.
|
||||
|
||||
The way to configure HotSwapAgent in case of using Java 8 or Java 11 is pretty different. By default, ACS 6.0 uses Java 8 and ACS 6.1 uses Java 11.
|
||||
|
||||
## Issue with Docker Toolbox
|
||||
|
||||
It's worth noting that the HotSwapAgent's hot reloading mechanism is not working for [Docker Toolbox](https://docs.docker.com/toolbox/toolbox_install_windows/)
|
||||
at the moment. Docker Toolbox is for older Mac and Windows systems that do not meet the requirements of [Docker for Mac](https://docs.docker.com/docker-for-mac/)
|
||||
and [Docker for Windows](https://docs.docker.com/docker-for-windows/).
|
||||
|
||||
This is due to an issue with the component used by HotSwapAgent to notify the changes in the compiled class files. HotSwapAgent uses the class
|
||||
[WatcherNIO2.java](https://github.com/HotswapProjects/HotswapAgent/blob/master/hotswap-agent-core/src/main/java/org/hotswap/agent/watch/nio/WatcherNIO2.java) to
|
||||
watch for the changes in the `extraClasspath` folder. That class is based on the Java class [WatchDir.java](https://docs.oracle.com/javase/tutorial/essential/io/examples/WatchDir.java)
|
||||
that, in Linux systems, is implemented using [inotify](http://man7.org/linux/man-pages/man7/inotify.7.html). It seems that inotify is not working properly
|
||||
with mounted volumes over Docker Toolbox (which internally uses VirtualBox).
|
||||
|
||||
You can track the evolution of this issue [here](https://github.com/moby/moby/issues/18246).
|
||||
|
||||
## Configuring HotSwapAgent in the project (Java 8)
|
||||
|
||||
1. Modify the file `PROJECT_ARTIFACT_ID-platform-docker/src/main/docker/Dockerfile` to copy the HotSwapAgent configuration file into the ACS container
|
||||
classpath:
|
||||
|
||||
```
|
||||
# Hot reload - Hotswap agent
|
||||
COPY hotswap-agent.properties $TOMCAT_DIR/webapps/alfresco/WEB-INF/classes
|
||||
```
|
||||
|
||||
2. Modify the file `PROJECT_ARTIFACT_ID-platform-docker/src/main/docker/Dockerfile` to append the commands to install and configure [DCEVM](http://dcevm.github.io/)
|
||||
and the HotSwapAgent java agent in the ACS container:
|
||||
|
||||
```
|
||||
# Download and Install the more capable DCEVM, which will allow more changes to classes, such as new methods
|
||||
RUN mkdir -p dcevm \
|
||||
&& curl -L -o dcevm/DCEVM-8u181-installer.jar "https://github.com/dcevm/dcevm/releases/download/light-jdk8u181%2B2/DCEVM-8u181-installer-build2.jar" \
|
||||
&& cd dcevm \
|
||||
&& jar -xvf DCEVM-8u181-installer.jar \
|
||||
&& cp linux_amd64_compiler2/product/libjvm.so /usr/java/default/jre/lib/amd64/server
|
||||
|
||||
# Download HotSwap Agent - it is used in the Docker Compose file.
|
||||
RUN cd /usr/local/tomcat \
|
||||
&& mkdir -p hotswap-agent \
|
||||
&& curl -L -o lib/hotswap-agent-1.3.0.jar "https://github.com/HotswapProjects/HotswapAgent/releases/download/RELEASE-1.3.0/hotswap-agent-1.3.0.jar"
|
||||
```
|
||||
|
||||
3. Modify the file `docker/docker-compose.yml` to change the ACS container `CATALINA_OPTS` environment property to use the HotSwap java agent:
|
||||
|
||||
```
|
||||
sample-project-acs:
|
||||
image: alfresco-content-services-sample-project:development
|
||||
build:
|
||||
dockerfile: ./Dockerfile
|
||||
context: ../../../sample-project-platform-docker/target
|
||||
environment:
|
||||
CATALINA_OPTS: "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8888 -javaagent:/usr/local/tomcat/lib/hotswap-agent-1.3.0.jar"
|
||||
...
|
||||
```
|
||||
|
||||
4. Modify the file `docker/docker-compose.yml` to change the ACS container command to avoid the execution of Tomcat with the Security Manager enabled (it makes
|
||||
the hot reloading tools fail):
|
||||
|
||||
```
|
||||
sample-project-acs:
|
||||
image: alfresco-content-services-sample-project:development
|
||||
build:
|
||||
dockerfile: ./Dockerfile
|
||||
context: ../../../sample-project-platform-docker/target
|
||||
environment:
|
||||
CATALINA_OPTS: "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8888 -javaagent:/usr/local/tomcat/lib/hotswap-agent-1.3.0.jar"
|
||||
command: ["catalina.sh", "run"]
|
||||
...
|
||||
```
|
||||
|
||||
5. Modify the file `docker/docker-compose.yml` to mount the target folders into the folder `/usr/local/tomcat/hotswap-agent` inside the ACS container:
|
||||
|
||||
```
|
||||
sample-project-acs:
|
||||
image: alfresco-content-services-sample-project:development
|
||||
build:
|
||||
dockerfile: ./Dockerfile
|
||||
context: ../../../sample-project-platform-docker/target
|
||||
environment:
|
||||
CATALINA_OPTS: "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8888 -javaagent:/usr/local/tomcat/lib/hotswap-agent-1.3.0.jar"
|
||||
command: ["catalina.sh", "run"]
|
||||
ports:
|
||||
- "${acs.port}:8080"
|
||||
- "${acs.debug.port}:8888"
|
||||
volumes:
|
||||
- alf-acs-volume:/usr/local/tomcat/alf_data
|
||||
- ../../../sample-project-platform-jar/target/classes:/usr/local/tomcat/hotswap-agent/sample-project-platform-jar/target/classes
|
||||
- ../../../integration-tests/target/test-classes:/usr/local/tomcat/hotswap-agent/integration-tests/target/test-classes
|
||||
...
|
||||
```
|
||||
|
||||
For more information about HotSwapAgent configuration for Java 8, please check the [HotSwapAgent documentation](http://hotswapagent.org/mydoc_quickstart.html).
|
||||
|
||||
## Configuring HotSwapAgent in the project (Java 11)
|
||||
|
||||
Using Java 11 and HotSwapAgent, it isn't necessary to configure the java agent and the alternative JVM as in previous versions. Instead, it is required
|
||||
to use an alternative pre-built JDK distribution. That JDK is based on OpenJDK and includes all the required modifications to run the HotSwapAgent properly.
|
||||
|
||||
In the context of the Alfresco SDK 4.0, this change is an issue because the JDK installation is inherited from the [Alfresco java docker image](https://github.com/Alfresco/alfresco-docker-base-java).
|
||||
It is necessary to modify the project ACS docker image to change the default java installation of the container's OS to the one provided by HotSwapAgent.
|
||||
|
||||
A way to implement the required modifications would be:
|
||||
|
||||
1. Download the last release of the Trava OpenJDK (Linux distribution) from [here](https://github.com/TravaOpenJDK/trava-jdk-11-dcevm/releases) and save it
|
||||
into the folder `PROJECT_ARTIFACT_ID-platform-docker/src/main/docker`.
|
||||
2. Modify the file `PROJECT_ARTIFACT_ID-platform-docker/src/main/docker/Dockerfile` to append the commands required to install and configure the custom JDK
|
||||
for the HotSwapAgent:
|
||||
|
||||
```
|
||||
# HOTSWAP AGENT
|
||||
# Install and configure Trava OpenJDK (OpenJDK pre-built with DCEVM and hotswap agent for Java 11)
|
||||
COPY trava-jdk-11-dcevm.tar.gz $TOMCAT_DIR
|
||||
RUN tar -xvf $TOMCAT_DIR/trava-jdk-11-dcevm.tar.gz -C /usr/java/ && \
|
||||
rm $TOMCAT_DIR/trava-jdk-11-dcevm.tar.gz && \
|
||||
alternatives --install /usr/bin/java java /usr/java/dcevm-11.0.1+7/bin/java 40000 && \
|
||||
alternatives --install /usr/bin/javac javac /usr/java/dcevm-11.0.1+7/bin/javac 40000 && \
|
||||
alternatives --install /usr/bin/jar jar /usr/java/dcevm-11.0.1+7/bin/jar 40000 && \
|
||||
alternatives --set java /usr/java/dcevm-11.0.1+7/bin/java && \
|
||||
alternatives --set javac /usr/java/dcevm-11.0.1+7/bin/javac && \
|
||||
alternatives --set jar /usr/java/dcevm-11.0.1+7/bin/jar && \
|
||||
ln -sfn /usr/java/dcevm-11.0.1+7 /usr/java/latest && \
|
||||
ln -sfn /usr/java/dcevm-11.0.1+7 /usr/java/default
|
||||
```
|
||||
|
||||
3. Modify the file `PROJECT_ARTIFACT_ID-platform-docker/src/main/docker/Dockerfile` to copy the HotSwapAgent configuration file into the ACS container
|
||||
classpath:
|
||||
|
||||
```
|
||||
# Copy the configuration properties file in the classpath
|
||||
COPY hotswap-agent.properties $TOMCAT_DIR/webapps/alfresco/WEB-INF/classes
|
||||
```
|
||||
|
||||
4. Modify the file `docker/docker-compose.yml` to change the ACS container command to avoid the execution of Tomcat with the Security Manager enabled (it makes
|
||||
the hot reloading tools fail):
|
||||
|
||||
```
|
||||
sample-project-acs:
|
||||
image: alfresco-content-services-sample-project:development
|
||||
build:
|
||||
dockerfile: ./Dockerfile
|
||||
context: ../../../sample-project-platform-docker/target
|
||||
environment:
|
||||
CATALINA_OPTS: "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8888"
|
||||
command: ["catalina.sh", "run"]
|
||||
...
|
||||
```
|
||||
|
||||
5. Modify the file `docker/docker-compose.yml` to mount the target folders into the folder `/usr/local/tomcat/hotswap-agent` inside the ACS container:
|
||||
|
||||
```
|
||||
sample-project-acs:
|
||||
image: alfresco-content-services-sample-project:development
|
||||
build:
|
||||
dockerfile: ./Dockerfile
|
||||
context: ../../../sample-project-platform-docker/target
|
||||
environment:
|
||||
CATALINA_OPTS: "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8888"
|
||||
command: ["catalina.sh", "run"]
|
||||
ports:
|
||||
- "${acs.port}:8080"
|
||||
- "${acs.debug.port}:8888"
|
||||
volumes:
|
||||
- alf-acs-volume:/usr/local/tomcat/alf_data
|
||||
- ../../../sample-project-platform-jar/target/classes:/usr/local/tomcat/hotswap-agent/sample-project-platform-jar/target/classes
|
||||
- ../../../integration-tests/target/test-classes:/usr/local/tomcat/hotswap-agent/integration-tests/target/test-classes
|
||||
...
|
||||
```
|
||||
|
||||
Instead of downloading the Trava OpenJDK distribution file and copying it to the container, the Dockerfile script could include directly the download of the
|
||||
file (via `curl` for instance), but that would slow down the creation of the ACS image each time it is rebuilt.
|
||||
|
||||
### Creating a custom HotSwapAgent ACS docker image
|
||||
|
||||
Another alternative to avoid this time overhead, due to the installation of the Trava OpenJDK distribution, is to create a custom docker image that installs
|
||||
and sets that custom JDK up.
|
||||
|
||||
A sample `Dockerfile` for that custom image for ACS 6.0 Community could be:
|
||||
|
||||
```
|
||||
FROM alfresco/alfresco-content-repository-community:6.0.7-ga
|
||||
|
||||
# HOTSWAP AGENT
|
||||
# Install and configure Trava OpenJDK (OpenJDK pre-built with DCEVM and hotswap agent for Java 11)
|
||||
COPY trava-jdk-11-dcevm.tar.gz $TOMCAT_DIR
|
||||
RUN tar -xvf $TOMCAT_DIR/trava-jdk-11-dcevm.tar.gz -C /usr/java/ && \
|
||||
rm $TOMCAT_DIR/trava-jdk-11-dcevm.tar.gz && \
|
||||
alternatives --install /usr/bin/java java /usr/java/dcevm-11.0.1+7/bin/java 40000 && \
|
||||
alternatives --install /usr/bin/javac javac /usr/java/dcevm-11.0.1+7/bin/javac 40000 && \
|
||||
alternatives --install /usr/bin/jar jar /usr/java/dcevm-11.0.1+7/bin/jar 40000 && \
|
||||
alternatives --set java /usr/java/dcevm-11.0.1+7/bin/java && \
|
||||
alternatives --set javac /usr/java/dcevm-11.0.1+7/bin/javac && \
|
||||
alternatives --set jar /usr/java/dcevm-11.0.1+7/bin/jar && \
|
||||
ln -sfn /usr/java/dcevm-11.0.1+7 /usr/java/latest && \
|
||||
ln -sfn /usr/java/dcevm-11.0.1+7 /usr/java/default
|
||||
```
|
||||
|
||||
That docker image can be built and pushed to your company Docker registry.
|
||||
|
||||
* Go to the folder where the `Dockerfile` is located and build the docker image:
|
||||
|
||||
```
|
||||
> docker build -t "alfresco/alfresco-content-repository-community-hotswap-agent:6.0.7-ga" .
|
||||
```
|
||||
|
||||
* Tag and push the image to your company Docker registry:
|
||||
|
||||
```
|
||||
> docker tag DOCKER_REGISTRY_URL/alfresco/alfresco-content-repository-community-hotswap-agent:6.0.7-ga alfresco/alfresco-content-repository-community-hotswap-agent:6.0.7-ga
|
||||
> docker push DOCKER_REGISTRY_URL/alfresco/alfresco-content-repository-community-hotswap-agent:6.0.7-ga
|
||||
```
|
||||
|
||||
Once the new image is available in the Docker registry, the maven property `docker.acs.image` can be modified in the main `pom.xml` file of the project to use
|
||||
that custom image:
|
||||
|
||||
```
|
||||
<docker.acs.image>alfresco/alfresco-content-repository-community-hotswap-agent</docker.acs.image>
|
||||
```
|
||||
|
||||
For more information about HotSwapAgent configuration for Java 11, please check the [HotSwapAgent documentation](http://hotswapagent.org/mydoc_quickstart-jdk11.html).
|
||||
|
||||
## Reloading changes in source code
|
||||
|
||||
1. Rebuild and restart the whole project (`run.sh/run.bat build_start`).
|
||||
|
||||
You'll recognize HotSwapAgent is working when you see similar log messages:
|
||||
|
||||
```
|
||||
HOTSWAP AGENT: 14:08:07.154 DEBUG (org.hotswap.agent.util.classloader.URLClassLoaderHelper) - Added extraClassPath URLs [file:/usr/local/tomcat/hotswap-agent/] to classLoader ParallelWebappClassLoader
|
||||
context: alfresco
|
||||
delegate: false
|
||||
----------> Parent Classloader:
|
||||
java.net.URLClassLoader@4c402120
|
||||
```
|
||||
|
||||
2. Before making any changes, let's run the sample webscript by opening your browser and typing `http://localhost:8080/alfresco/s/sample/helloworld`.
|
||||
|
||||
This is a sample webscript generated in every project created using SDK 4.0 and the platform artifact.
|
||||
|
||||
|
||||
|
||||
3. Locate `HelloWorldWebScript.java` in the `src/main/java/.../platformsample` folder of your project (If you are using an All-In-One project, the folder is
|
||||
located in the platform sub-project).
|
||||
|
||||
4. Edit it using your preferred editor and change the code so that `HelloFromJava` becomes `HelloFromMe`:
|
||||
|
||||
```
|
||||
model.put(“fromJava”,”HelloFromMe”);
|
||||
```
|
||||
|
||||
5. Save the file and compile the Java class (using your preferred IDE or the `mvn compile` command).
|
||||
|
||||
A number of log messages appear in the Alfresco project terminal, for example:
|
||||
|
||||
```
|
||||
HOTSWAP AGENT: 14:10:29.887 DEBUG (org.hotswap.agent.watch.nio.WatcherNIO2) - Watch event 'ENTRY_MODIFY' on '/usr/local/tomcat/hotswap-agent/sample-project-platform-jar/target/classes/com/example/platformsample/HelloWorldWebScript.class' --> HelloWorldWebScript.class
|
||||
HOTSWAP AGENT: 14:10:30.319 DEBUG (org.hotswap.agent.command.impl.SchedulerImpl) - Executing pluginManager.hotswap([class com.example.platformsample.HelloWorldWebScript])
|
||||
HOTSWAP AGENT: 14:10:30.368 RELOAD (org.hotswap.agent.config.PluginManager) - Reloading classes [com.example.platformsample.HelloWorldWebScript] (autoHotswap)
|
||||
HOTSWAP AGENT: 14:10:30.387 DEBUG (org.hotswap.agent.plugin.jdk.JdkPlugin) - Flushing com.example.platformsample.HelloWorldWebScript from introspector
|
||||
HOTSWAP AGENT: 14:10:30.394 DEBUG (org.hotswap.agent.plugin.jdk.JdkPlugin) - Flushing com.example.platformsample.HelloWorldWebScript from ObjectStreamClass caches
|
||||
HOTSWAP AGENT: 14:10:30.399 DEBUG (org.hotswap.agent.plugin.jvm.ClassInitPlugin) - Adding $ha$$clinit to class: com.example.platformsample.HelloWorldWebScript
|
||||
HOTSWAP AGENT: 14:10:30.422 DEBUG (org.hotswap.agent.plugin.jvm.ClassInitPlugin) - Skipping old field logger
|
||||
HOTSWAP AGENT: 14:10:33.312 DEBUG (org.hotswap.agent.config.PluginManager) - ... reloaded classes [com.example.platformsample.HelloWorldWebScript] (autoHotswap)
|
||||
```
|
||||
|
||||
6. Refresh the browser to see the updated message:
|
||||
|
||||
|
||||
|
||||
By changing the code and compiling it again, the changes have been dynamically received from Alfresco Content Services.
|
||||
170
docs/advanced-topics/hot-reloading/jrebel.md
Normal file
170
docs/advanced-topics/hot-reloading/jrebel.md
Normal file
@ -0,0 +1,170 @@
|
||||
---
|
||||
Title: How to configure and use JRebel
|
||||
Added: v3.0.0
|
||||
Last reviewed: 2019-01-14
|
||||
---
|
||||
# How to configure and use JRebel
|
||||
|
||||
[JRebel](https://zeroturnaround.com/software/jrebel/) is the agent that enables you to do hot reloading. This allows you to modify the application code,
|
||||
and view the changes without having to restart Alfresco Tomcat (or the ACS Docker container).
|
||||
|
||||
A prerequisite to this tutorial is having an Alfresco project created with Alfresco SDK 4.0, using the All-In-One archetype, or the Platform JAR archetype.
|
||||
It's worth noting that hot reloading is only supported on the platform, and not in Alfresco Share.
|
||||
|
||||
An open source and free of charge alternative to JRebel is HotSwapAgent. For more details, see the [HotSwapAgent website](http://hotswapagent.org/index.html).
|
||||
|
||||
JRebel can be installed in several ways: for example, using an IDE or in "standalone" mode. Various IDEs are supported, including Eclipse and IntelliJ. The
|
||||
standalone installation is useful if you want to use hot reloading from the command line.
|
||||
|
||||
## Installing JRebel standalone (from the command line)
|
||||
|
||||
1. Download JRebel in standalone mode and unpack it in your preferred location.
|
||||
2. Run the activate-gui.sh script to activate your installation.
|
||||
|
||||
_Note that a license is required. In this step you will be able to request a trial license._
|
||||
|
||||
## Installing JRebel using Eclipse IDE
|
||||
|
||||
1. Open Eclipse and go to `Help > Eclipse Marketplace`….
|
||||
2. Search for JRebel and select Install.
|
||||
3. Restart Eclipse to complete the installation.
|
||||
4. Select `Help > JRebel > Activation` to activate your installation.
|
||||
|
||||
_Note that a license is required. In this step you will be able to request a trial license._
|
||||
|
||||
5. Select `Help > JRebel > Configuration > Remote servers` to add a new remote server.
|
||||
6. Give a descriptive name to the new server and set the `Server URL` as `http://localhost:8080/alfresco`.
|
||||
|
||||
|
||||
|
||||
7. Select the checkbox to enable the server synchronisation and the checkbox to `Synchronize on build`.
|
||||
|
||||
|
||||
|
||||
8. Select `Help > JRebel > Configuration > Projects` and select the checkbox to enable JRebel and the remote server support for required projects (the complete
|
||||
project in case of the Platform Jar archetype or the `PROJECT_ARTIFACT_ID-platform-jar` and `integration-tests` modules in case of the All-In-One archetype).
|
||||
|
||||
|
||||
|
||||
## Installing JRebel using IntelliJ IDEA
|
||||
|
||||
1. Open IntelliJ and go to `Preferences > Plugins`….
|
||||
2. Search for JRebel and select Install.
|
||||
3. Restart IntelliJ to complete the installation.
|
||||
4. Select `Preferences > JRebel > JRebel License` to activate your installation.
|
||||
|
||||
_Note that a license is required. In this step you will be able to request a trial license._
|
||||
|
||||
5. Select `Preferences > JRebel > Remote Servers` to add a new remote server.
|
||||
6. Give a descriptive name to the new server and set the `Server URL` as `http://localhost:8080/alfresco.
|
||||
|
||||
|
||||
|
||||
7. Select the checkbox to enable the server synchronisation and the checkbox to `Synchronize on build`.
|
||||
|
||||
|
||||
|
||||
8. Open the JRebel Panel and select the checkbox to enable JRebel and the remote server support for required projects (the complete project in case of the
|
||||
Platform Jar archetype or the `PROJECT_ARTIFACT_ID-platform-jar` and `integration-tests` modules in case of the All-In-One archetype).
|
||||
|
||||
|
||||
|
||||
## Configuring JRebel in the project
|
||||
|
||||
By default, JRebel is not set up in the projects generated making use of the Alfresco SDK archetypes. So, in order to enable it, you'll need to follow the next
|
||||
steps:
|
||||
|
||||
1. Once JRebel is activated, copy `JREBEL_BASE_DIR/jrebel.jar` and `JREBEL_BASE_DIR/lib/libjrebel64.so` to
|
||||
`PROJECT_ARTIFACT_ID-platform-docker/src/main/docker` folder in case of the All-In-One archetype or `PROJECT_ARTIFACT_ID/src/main/docker` folder in case of the
|
||||
Platform Jar archetype.
|
||||
2. Modify the file `PROJECT_ARTIFACT_ID-platform-docker/src/main/docker/Dockerfile` to copy the JRebel files into the platform container:
|
||||
```
|
||||
# Hot reload - JRebel
|
||||
COPY jrebel.jar /jrebel.jar
|
||||
COPY libjrebel64.so /libjrebel64.so
|
||||
```
|
||||
3. Modify the file `docker/docker-compose.yml` to change the `CATALINA_OPTS` environment property to use the JRebel agent and the remote plugin. Add the
|
||||
command to avoid executing Tomcat with the Security Manager enabled (it makes the hot reloading tools to fail):
|
||||
```
|
||||
sample-project-acs:
|
||||
image: alfresco-content-services-sample-project:development
|
||||
build:
|
||||
dockerfile: ./Dockerfile
|
||||
context: ../../../sample-project-platform-docker/target
|
||||
environment:
|
||||
CATALINA_OPTS: "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8888 -agentpath:/libjrebel64.so -Drebel.remoting_plugin=true"
|
||||
command: ["catalina.sh", "run"]
|
||||
ports:
|
||||
- "${acs.port}:8080"
|
||||
- "${acs.debug.port}:8888"
|
||||
volumes:
|
||||
- alf-acs-volume:/usr/local/tomcat/alf_data
|
||||
depends_on:
|
||||
- sample-project-postgres
|
||||
```
|
||||
|
||||
## Reloading changes in source code
|
||||
|
||||
1. Rebuild and restart the whole project (`run.sh/run.bat build_start`).
|
||||
|
||||
You'll recognize JRebel is working when you see similar log messages:
|
||||
|
||||
```
|
||||
2017-05-16 15:28:12 JRebel: Starting logging to file: /home/alfresco/.jrebel/jrebel.log
|
||||
2017-05-16 15:28:12 JRebel:
|
||||
2017-05-16 15:28:12 JRebel: #############################################################
|
||||
2017-05-16 15:28:12 JRebel:
|
||||
2017-05-16 15:28:12 JRebel: JRebel Agent 7.0.8 (999999999999)
|
||||
2017-05-16 15:28:12 JRebel: (c) Copyright ZeroTurnaround AS, Estonia, Tartu.
|
||||
2017-05-16 15:28:12 JRebel:
|
||||
2017-05-16 15:28:12 JRebel: Over the last 2 days JRebel prevented
|
||||
2017-05-16 15:28:12 JRebel: at least 1 redeploys/restarts saving you about 0 hours.
|
||||
2017-05-16 15:28:12 JRebel:
|
||||
2017-05-16 15:28:12 JRebel: Licensed to XXXX XXXX (XXXX)
|
||||
2017-05-16 15:28:12 JRebel:
|
||||
2017-05-16 15:28:12 JRebel: License type: evaluation
|
||||
2017-05-16 15:28:12 JRebel: Valid from: XXX 99, 9999
|
||||
2017-05-16 15:28:12 JRebel: Valid until: XXX 99, 9999
|
||||
2017-05-16 15:28:12 JRebel:
|
||||
2017-05-16 15:28:12 JRebel: You are using an EVALUATION license.
|
||||
2017-05-16 15:28:12 JRebel: Days left until license expires: 99
|
||||
2017-05-16 15:28:12 JRebel:
|
||||
2017-05-16 15:28:12 JRebel: To extend your evaluation or purchase a license,
|
||||
2017-05-16 15:28:12 JRebel: contact sales@zeroturnaround.com.
|
||||
2017-05-16 15:28:12 JRebel:
|
||||
2017-05-16 15:28:12 JRebel: If you think this is an error, contact support@zeroturnaround.com.
|
||||
2017-05-16 15:28:12 JRebel:
|
||||
2017-05-16 15:28:12 JRebel:
|
||||
2017-05-16 15:28:12 JRebel: #############################################################
|
||||
```
|
||||
|
||||
2. Before making any changes, let's run the sample webscript by opening your browser and typing `http://localhost:8080/alfresco/s/sample/helloworld`.
|
||||
|
||||
This is a sample webscript generated in every project created using SDK 4.0 and the platform artifact.
|
||||
|
||||
|
||||
|
||||
3. Locate `HelloWorldWebScript.java` in the `src/main/java/.../platformsample` folder of your project (If you are using an All-In-One project, the folder is
|
||||
located in the platform sub-project).
|
||||
|
||||
4. Edit it using your preferred editor and change the code so that `HelloFromJava` becomes `HelloFromMe`:
|
||||
|
||||
```
|
||||
model.put(“fromJava”,”HelloFromMe”);
|
||||
```
|
||||
|
||||
5. Save the file and compile the Java class (using your preferred IDE or the `mvn compile` command).
|
||||
|
||||
A number of log messages appear in the Alfresco project terminal, for example:
|
||||
|
||||
```
|
||||
... JRebel: Reloading class 'com.example.platformsample.HelloWorldWebScript'.
|
||||
... JRebel: Reconfiguring bean 'webscript.alfresco.tutorials.helloworld.get'
|
||||
[com.example.platformsample.HelloWorldWebScript]
|
||||
```
|
||||
|
||||
6. Refresh the browser to see the updated message:
|
||||
|
||||
|
||||
|
||||
By changing the code and compiling it again, the changes have been dynamically received from Alfresco Content Services.
|
||||
32
docs/advanced-topics/integration-testing/README.md
Normal file
32
docs/advanced-topics/integration-testing/README.md
Normal file
@ -0,0 +1,32 @@
|
||||
---
|
||||
Title: Integration testing
|
||||
Added: v3.0.0
|
||||
Last reviewed: 2019-01-16
|
||||
---
|
||||
# Integration testing
|
||||
|
||||
_"Integration testing is the phase in software testing where individual software modules are combined and tested as a group. It occurs after unit testing and
|
||||
before validation testing. Integration testing takes as its input modules that have been unit tested, groups them in larger aggregates, applies tests defined
|
||||
in an integration test plan to those aggregates, and delivers as its output the integrated system ready for system testing. [Wikipedia]."_
|
||||
|
||||
Even if the definition of integration testing is a general description, the concept is also valid for Alfresco projects.
|
||||
|
||||
The Alfresco SDK 4.0 keeps the same general idea of integration testing provided by SDK 3.0, but this new version reshapes it slightly to leverage on a
|
||||
Docker-oriented environment.
|
||||
|
||||
Here are the basics to understanding and using integration testing in the context of projects created with the SDK, from a technical perspective:
|
||||
* SDK 4.0 develops integration tests for the platform only. Currently, the integration tests that the SDK is able to manage by default is related to
|
||||
Alfresco Content Services (ACS) only.
|
||||
* Integration tests require an ACS instance to be up and running. You will see that all the scripts and commands are designed to easily manage this
|
||||
requirement, but the prerequisite for the SDK is that an ACS instance is available.
|
||||
* If you're running a project created with a Platform JAR archetype, integration tests are not provided by default. However, you can copy them from your
|
||||
All-In-One project.
|
||||
|
||||
## How SDK's integration tests work
|
||||
|
||||
If you want to know how the SDK's integration tests work and what are the basic tests included in the archetypes, then visit [How SDK's integration tests work](it-working.md).
|
||||
|
||||
## How to run SDK's integration tests
|
||||
|
||||
If you want to know how you can execute the SDK's integration tests in different environments and some considerations about it, then visit
|
||||
[How to run SDK's integration tests](it-running.md).
|
||||
116
docs/advanced-topics/integration-testing/it-running.md
Normal file
116
docs/advanced-topics/integration-testing/it-running.md
Normal file
@ -0,0 +1,116 @@
|
||||
---
|
||||
Title: How to run SDK's integration tests
|
||||
Added: v3.0.0
|
||||
Last reviewed: 2019-01-16
|
||||
---
|
||||
# How to run SDK's integration tests
|
||||
|
||||
Running the integration tests of a project generated from the Alfresco SDK 4.0 archetypes is pretty easy. Let's distinguish different cases of executing the
|
||||
integration tests.
|
||||
|
||||
## Command line
|
||||
|
||||
If you want to run the integration tests from the command line you'll have to use the utility scripts provided by all the projects generated from the
|
||||
archetypes. These are `run.sh` if you're on Unix systems or `run.bat` if you're on Windows systems.
|
||||
|
||||
If you want to spin up a new dockerised environment with ACS, run the integration tests and stop that environment, you'll use the `build_test` goal:
|
||||
|
||||
```
|
||||
$ ./run.sh build_test
|
||||
```
|
||||
|
||||
If you want all your previous data in the docker environment to be wiped out before the execution of the integration tests, remember to call the `purge` goal
|
||||
before the `build_start` goal:
|
||||
|
||||
```
|
||||
$ ./run.sh purge
|
||||
$ ./run.sh build_test
|
||||
```
|
||||
|
||||
The `build_test` goal will execute the next list of tasks:
|
||||
* Stop any previous execution of the dockerised environment.
|
||||
* Compile all the source code.
|
||||
* Rebuild the custom Docker images of the project.
|
||||
* Start a new dockerised environment.
|
||||
* Execute the integration tests.
|
||||
* Show the logs of the docker containers during the tests execution.
|
||||
* Stop the dockerised environment.
|
||||
|
||||
If your dockerised environment is already started and you simply want to execute the integration tests against that existing ACS instance, then use the `test`
|
||||
goal:
|
||||
|
||||
```
|
||||
$ ./run.sh test
|
||||
```
|
||||
|
||||
### Configuring a custom ACS endpoint location
|
||||
|
||||
If you want to run your integration tests against an ACS instance not exposed in `http://localhost:8080/alfresco` you'll need to modify a maven property
|
||||
before executing the tests.
|
||||
|
||||
The maven property for the test ACS instance endpoint location is `acs.endpoint.path` and you can configure it in the `pom.xml` file in the root folder of your
|
||||
project:
|
||||
|
||||
```
|
||||
<properties>
|
||||
...
|
||||
<test.acs.endpoint.path>http://192.168.99.100:8080/alfresco</test.acs.endpoint.path>
|
||||
..
|
||||
</properties>
|
||||
```
|
||||
|
||||
This parameter is **specially important** if you're running your dockerised environment using [Docker Toolbox](https://docs.docker.com/toolbox/) instead of
|
||||
[Docker Desktop](https://www.docker.com/products/docker-desktop). If that is the case, then the Docker container exposed ports are not mapped in the hosted
|
||||
machine as `localhost` but as an assigned IP address (i.e. `192.168.99.100`).
|
||||
|
||||
## Eclipse IDE
|
||||
|
||||
If your project is available in Eclipse, you can easily run one or more of the integration tests directly from your IDE.
|
||||
|
||||
To run the integration tests:
|
||||
|
||||
1. In order to properly execute the integration tests the dockerised environment must be already up and running. So, before executing the tests you must run
|
||||
the `build_start` or the `start` goal of the `run` script.
|
||||
|
||||
2. Open the project using the IDE.
|
||||
|
||||
3. Select the classes for the integration tests (either one, some, or the whole package).
|
||||
|
||||
4. Right click and select `Run As ...`, then click `JUnit Test`.
|
||||
|
||||
|
||||
|
||||
Once the tests have completed (typically, after a few seconds), the results are presented.
|
||||
|
||||
|
||||
|
||||
When using an IDE, the source code related to the integration tests is the one deployed directly on the platform side. This means that an update in the code
|
||||
for the Java classes will be included when you run the integration tests _if and only if_ they are deployed in the platform. To avoid stopping/starting
|
||||
Alfresco Content Services with every change, use **hot reloading** as the only way to deploy the new version of the Java classes. For more details, see
|
||||
[JRebel](../hot-reloading/jrebel.md) / [HotSwapAgent](../hot-reloading/hotswap-agent.md) Hot reloading.
|
||||
|
||||
## IntelliJ IDEA IDE
|
||||
|
||||
If your project is available in IntelliJ IDEA, you can easily run one or more of the integration tests directly from your IDE.
|
||||
|
||||
To run the integration tests:
|
||||
|
||||
1. In order to properly execute the integration tests the dockerised environment must be already up and running. So, before executing the tests you must run
|
||||
the `build_start` or the `start` goal of the `run` script.
|
||||
|
||||
2. Open the project using the IDE.
|
||||
|
||||
3. Select the classes for the integration tests (either one, some, or the whole package).
|
||||
|
||||
4. Right click and select `Run Tests`.
|
||||
|
||||
|
||||
|
||||
Once the tests have completed (typically, after a few seconds), the results are presented.
|
||||
|
||||
|
||||
|
||||
When using an IDE, the source code related to the integration tests is the one deployed directly on the platform side. This means that an update in the code
|
||||
for the Java classes will be included when you run the integration tests _if and only if_ they are deployed in the platform. To avoid stopping/starting
|
||||
Alfresco Content Services with every change, use **hot reloading** as the only way to deploy the new version of the Java classes. For more details, see
|
||||
[JRebel](../hot-reloading/jrebel.md) / [HotSwapAgent](../hot-reloading/hotswap-agent.md) Hot reloading.
|
||||
160
docs/advanced-topics/integration-testing/it-working.md
Normal file
160
docs/advanced-topics/integration-testing/it-working.md
Normal file
@ -0,0 +1,160 @@
|
||||
---
|
||||
Title: How SDK's integration tests work
|
||||
Added: v3.0.0
|
||||
Last reviewed: 2019-01-16
|
||||
---
|
||||
# How SDK's integration tests work
|
||||
|
||||
The Alfresco SDK's integration tests are primarily supported by a utility module included in the SDK called [Alfresco Rapid Application Development](https://github.com/Alfresco/alfresco-sdk/tree/master/modules/alfresco-rad)
|
||||
(alfresco-rad). This module basically enables the execution of the integration tests within the context of a running Alfresco Content Service (ACS) instance.
|
||||
|
||||
## Alfresco Rapid Application Development (Alfresco RAD)
|
||||
|
||||
The Alfresco RAD is an Alfresco module which main functionality is offering the ability to execute integration tests in a real ACS context. The core classes
|
||||
that conforms the Alfresco RAD module are:
|
||||
* [AlfrescoTestRunner](https://github.com/Alfresco/alfresco-sdk/blob/master/modules/alfresco-rad/src/main/java/org/alfresco/rad/test/AlfrescoTestRunner.java).
|
||||
A JUnit test runner that is designed to work with an ACS instance. It detects if it's executing a test inside of a running ACS instance.
|
||||
If that is the case the tests are all run normally. If the test is being run from outside the repository, then, instead of running the actual test, an HTTP
|
||||
request is made to a Web Script (`RunTestWebScript`) in a running Alfresco instance.
|
||||
* [RunTestWebScript](https://github.com/Alfresco/alfresco-sdk/blob/master/modules/alfresco-rad/src/main/java/org/alfresco/rad/test/RunTestWebScript.java).
|
||||
This Web Script works in consort with the `AlfrescoTestRunner`. When a test is run from outside the repository, the Alfresco test runner sends a proxied
|
||||
request to perform the test to this script. This runs the test and wraps the results up so that the test initiator can be fooled into thinking they are
|
||||
running the tests locally.
|
||||
* [AbstractAlfrescoIT](https://github.com/Alfresco/alfresco-sdk/blob/master/modules/alfresco-rad/src/main/java/org/alfresco/rad/test/AbstractAlfrescoIT.java).
|
||||
Abstract integration test class that gives access to the Alfresco Spring Application context and the `ServiceRegistry` that should be used when accessing
|
||||
Alfresco Services.
|
||||
* [Remote](https://github.com/Alfresco/alfresco-sdk/blob/master/modules/alfresco-rad/src/main/java/org/alfresco/rad/test/Remote.java). The `AlfrescoTestRunner`
|
||||
class has to determine where the ACS instance endpoint is exposed to send the proxied request to the `RunTestWebScript`. It uses, in order, the next three
|
||||
mechanisms:
|
||||
* The `Remote` annotation. If the test is annotated with `@Remote`, then it uses the `endpoint` property to determine the ACS endpoint.
|
||||
* The `acs.endpoint.path` Java system property. If the Java system property is set, then its value is used as the ACS endpoint.
|
||||
* A default value. If none of the previous mechanisms returned a value, then the default value `http://localhost:8080/alfresco` is used.
|
||||
|
||||
In summary, if you want to execute your integration tests inside an existing ACS instance, you'll need to annotate them with the JUnit `RunWith` annotation
|
||||
and set the value to `AlfrescoTestRunner.class`. If you want to customise the default ACS endpoint location, you can either annotate your tests with `Remote`
|
||||
or set the Java system property `acs.endpoint.path`.
|
||||
|
||||
## Integration tests configuration in the All-In-One project
|
||||
|
||||
So, taking into account the previous section, let's see how the integration tests are configured in a project generated from the SDK 4.0 All-In-One archetype.
|
||||
|
||||
* The maven dependencies required to execute the integration tests are deployed to the ACS Docker image in the `PROJECT_ARTEFACTID-platform-docker` maven
|
||||
module using the `maven-dependency-plugin`. The configuration is done in the file `PROJECT_ARTEFACTID-platform-docker/pom.xml`:
|
||||
|
||||
```
|
||||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-dependency-plugin</artifactId>
|
||||
<executions>
|
||||
<!-- Copy the repository extension and the dependencies required for execute integration tests -->
|
||||
<execution>
|
||||
<id>copy-repo-extension</id>
|
||||
<phase>pre-integration-test</phase>
|
||||
<goals>
|
||||
<goal>copy</goal>
|
||||
</goals>
|
||||
<configuration>
|
||||
<artifactItems>
|
||||
...
|
||||
<!-- Test dependencies -->
|
||||
<!-- We need these dependencies installed in ACS in order to execute the test remotely making use of the Alfresco RAD module -->
|
||||
<artifactItem>
|
||||
<groupId>org.alfresco.maven</groupId>
|
||||
<artifactId>alfresco-rad</artifactId>
|
||||
<version>${alfresco.sdk.version}</version>
|
||||
<overWrite>false</overWrite>
|
||||
<outputDirectory>${project.build.directory}/extensions</outputDirectory>
|
||||
</artifactItem>
|
||||
<artifactItem>
|
||||
<groupId>org.alfresco</groupId>
|
||||
<artifactId>integration-tests</artifactId>
|
||||
<version>1.0-SNAPSHOT</version>
|
||||
<classifier>tests</classifier>
|
||||
<overWrite>false</overWrite>
|
||||
<outputDirectory>${project.build.directory}/extensions</outputDirectory>
|
||||
</artifactItem>
|
||||
<artifactItem>
|
||||
<groupId>junit</groupId>
|
||||
<artifactId>junit</artifactId>
|
||||
<version>4.12</version>
|
||||
<overWrite>false</overWrite>
|
||||
<outputDirectory>${project.build.directory}/extensions</outputDirectory>
|
||||
</artifactItem>
|
||||
<artifactItem>
|
||||
<groupId>org.mockito</groupId>
|
||||
<artifactId>mockito-all</artifactId>
|
||||
<version>1.9.5</version>
|
||||
<overWrite>false</overWrite>
|
||||
<outputDirectory>${project.build.directory}/extensions</outputDirectory>
|
||||
</artifactItem>
|
||||
<artifactItem>
|
||||
<groupId>org.apache.httpcomponents</groupId>
|
||||
<artifactId>httpclient</artifactId>
|
||||
<version>4.5.2</version>
|
||||
<overWrite>false</overWrite>
|
||||
<outputDirectory>${project.build.directory}/extensions</outputDirectory>
|
||||
</artifactItem>
|
||||
</artifactItems>
|
||||
</configuration>
|
||||
</execution>
|
||||
...
|
||||
</executions>
|
||||
</plugin>
|
||||
```
|
||||
|
||||
* The `integration-tests` maven module include the definition of all the integration test classes to be executed against the existing ACS instance. The test
|
||||
classes are included in the folder `integration-tests/src/test/java`.
|
||||
|
||||
* The `integration-tests` maven `pom.xml` file adds the configuration of the `acs.endpoint.path` in case it is required. This is done using the
|
||||
`maven-failsafe-plugin`:
|
||||
|
||||
```
|
||||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-failsafe-plugin</artifactId>
|
||||
<configuration>
|
||||
<systemPropertyVariables>
|
||||
<acs.endpoint.path>${test.acs.endpoint.path}</acs.endpoint.path>
|
||||
</systemPropertyVariables>
|
||||
</configuration>
|
||||
</plugin>
|
||||
```
|
||||
|
||||
This is specially useful when the ACS endpoint is not exposed at the default location (`http://localhost:8080/alfresco`). This property is important when the
|
||||
development environment is run using Docker Toolbox (old Windows and MacOS versions). In this case, the container exposed ports are not mapped to `localhost`,
|
||||
but to a custom IP provided by the Virtual Box virtual machine (i.e. `http://192.168.99.100:8080/alfresco`).
|
||||
|
||||
* The All-In-One project utility scripts (`run.sh` / `run.bat`) offer two different tasks to execute the integration tests:
|
||||
* `build_test`. It builds the whole project, recreates the ACS and Share docker images, starts the dockerised environment, executes the integration tests
|
||||
from the `integration-tests` module and stops the environment.
|
||||
* `test`. It simply executes the integration tests (the environment must be already started).
|
||||
|
||||
## Sample tests included in the generated project
|
||||
|
||||
The All-In-One archetype includes some basic integration tests that demonstrate the way you can implement the integration tests of your custom module.
|
||||
|
||||
### `CustomContentModelIT`: Checking the correct existence and setup of a custom model
|
||||
|
||||
This integration test verifies the existence of the `{http://www.acme.org/model/content/1.0}contentModel` in the Alfresco Content Services instance. It also
|
||||
creates a new node in the repository with the following features:
|
||||
* The node is named `AcmeFile.txt`.
|
||||
* The node type is set to `{http://www.acme.org/model/content/1.0}document`.
|
||||
* The node property `securityClassification` is set to `Company Confidential`.
|
||||
* The aspect `cm:titled` is added to the new node.
|
||||
|
||||
Once created, some Java assertions are raised to check the correct definition of the node. As a last task, the node is deleted from the repository to clean
|
||||
the environment.
|
||||
|
||||
### `DemoComponentIT`: Checking the Alfresco Content Services DemoComponent component
|
||||
|
||||
This integration test verifies the existence of the `DemoComponent` component deployed in the Alfresco Content Services instance. You can find the definition
|
||||
of the `DemoComponent` as a custom component of a project created with the All-In-One archetype. For more details, see the class definition in
|
||||
`PROJECT_ARTEFACTID-platform-jar/src/main/java/com/example/platformsample/DemoComponent.java`.
|
||||
|
||||
The integration test retrieves the `DemoComponent` bean from the Alfresco Content Services instance (see `testGetCompanyHome()`), and requests the Company
|
||||
Home component. In addition, some Java assertions check if Company Home is identified correctly and has seven children stored in it.
|
||||
|
||||
### `HelloWorldWebScriptIT`: Checking the Alfresco Content Services helloworld webscript
|
||||
|
||||
This integration test is the simplest one, and verifies the existence and the response of the `helloworld` web script in the Alfresco Content Services instance.
|
||||
The test invokes the web script at the URL `http://localhost:8080/alfresco/service/sample/helloworld` and checks the response using some Java assertions.
|
||||
60
docs/advanced-topics/switching-versions.md
Normal file
60
docs/advanced-topics/switching-versions.md
Normal file
@ -0,0 +1,60 @@
|
||||
---
|
||||
Title: Switching Alfresco Content Services and Share versions
|
||||
Added: v3.0.0
|
||||
Last reviewed: 2019-01-16
|
||||
---
|
||||
# Switching Alfresco Content Services and Share versions
|
||||
|
||||
The latest version of the Alfresco SDK supports different versions for Alfresco Content Services and Alfresco Share. Since each product is no longer
|
||||
released under one common version number, ACS (i.e. alfresco.war) and the Share UI (share.war) are now released with individual version numbers.
|
||||
|
||||
By default, SDK 4.0 is configured to generate projects using the most recent version of ACS and Share. You can easily change one (or both) versions by
|
||||
simply updating the `pom.xml` file in your project. The compatibility of these versions is up to you, however you should check in advance the right versions
|
||||
to use.
|
||||
|
||||
When editing `pom.xml` you will see a number of properties that define the Alfresco Content Services platform version and the Alfresco Share version, such as:
|
||||
|
||||
```
|
||||
<alfresco.platform.version>6.0.7-ga</alfresco.platform.version>
|
||||
<alfresco.share.version>6.0.c</alfresco.share.version>
|
||||
```
|
||||
**(confirmation required)**
|
||||
|
||||
Before continuing, always remember to start from a newly generated SDK project before changing the version numbers. We do not recommend changing the versions
|
||||
using developed customizations or source code.
|
||||
|
||||
This article is focused on the Community version. If you want to switch to Alfresco Enterprise, please visit [Working with Enterprise](working-with-enterprise/README.md).
|
||||
|
||||
The supported versions are explained in the next sections of this article.
|
||||
|
||||
## Switch to Alfresco version 6.0.x
|
||||
|
||||
Starting from a newly created Alfresco SDK 4.0 project (All-In-One, Platform JAR, or Share JAR), let’s replace the two properties with the following ones.
|
||||
|
||||
1. Open the pom.xml in your generated project.
|
||||
|
||||
2. Replace the properties with the following:
|
||||
|
||||
```
|
||||
<alfresco.platform.version>6.0.7-ga</alfresco.platform.version>
|
||||
<alfresco.share.version>6.0.c</alfresco.share.version>
|
||||
```
|
||||
|
||||
In this example we have shown the switch to version 6.0.7-ga. Feel free to use the correct version for your project, paying attention to the compatible versions
|
||||
of Alfresco Content Services and Alfresco Share.
|
||||
|
||||
3. After changing the versions, delete all the previous data of your development Docker environment:
|
||||
|
||||
```
|
||||
$ ./run.sh purge
|
||||
```
|
||||
|
||||
4. Rebuild and restart the project:
|
||||
|
||||
```
|
||||
$ ./run.sh build_start
|
||||
```
|
||||
|
||||
**IMPORTANT:** Alfresco 6.1 is ready to work with JDK 11, but Alfresco 6.0 needs to be compiled and run using JDK 8, so please take this into account when you
|
||||
switch from version 6.1.x to 6.0.x. If you compile Alfresco 6.0.x with JDK 11 you'll experience the issue described in the [Troubleshooting page](../troubleshooting.md)
|
||||
about wrong JDK versions.
|
||||
75
docs/advanced-topics/working-with-enterprise/README.md
Normal file
75
docs/advanced-topics/working-with-enterprise/README.md
Normal file
@ -0,0 +1,75 @@
|
||||
---
|
||||
Title: Working with Enterprise
|
||||
Added: v3.0.0
|
||||
Last reviewed: 2019-01-15
|
||||
---
|
||||
# Working with Enterprise
|
||||
|
||||
By default the Alfresco SDK will use Community Edition releases but it can be configured to use Enterprise Edition releases. Here you will learn how to
|
||||
set up a project to work with an Enterprise Edition release, highlighting the changes required to make it work.
|
||||
|
||||
If you would like to work with the Alfresco Enterprise Edition, then this requires just a few property changes and a license installation. You also need
|
||||
to have access to the private Alfresco Nexus repository and the private Alfresco Quay.io Docker registry. See:
|
||||
* [How to configure private Alfresco Nexus repository](enterprise-mvn-repo.md).
|
||||
* [How to configure private Alfresco Docker registry](enterprise-docker-registry.md).
|
||||
|
||||
## Installing the license
|
||||
|
||||
The very first task to complete is about installing an enterprise license, otherwise the server will remain in read-only mode. This task is required if and
|
||||
only if you used the All-In-One archetype or the Platform JAR archetype to generate your project. If you used the Share JAR archetype to generate your project,
|
||||
feel free to ignore this task and move on the next one.
|
||||
|
||||
If you are an Alfresco Partner or Customer, you can request an enterprise license by you opening a ticket on the [Alfresco Support Portal](http://support.alfresco.com).
|
||||
The Enterprise license is nothing more and nothing less than a file with `lic` extension. The Enterprise license file goes into `src/main/docker/license`
|
||||
folder (this folder will be located under the platform JAR submodule if you're using the All-In-One archetype). The license will be copied into the ACS Docker
|
||||
container before it is started. The license file name doesn't matter, but make sure that you keep it simple and maintain the `lic` extension.
|
||||
|
||||
## Configuring the Enterprise release
|
||||
|
||||
The configuration of the Enterprise version is straightforward when using the `pom.xml` configuration file stored in the root folder of your project.
|
||||
You'll need to update the following settings in the `pom.xml` file:
|
||||
|
||||
* Change the _bill of materials_ (BOM) dependency name:
|
||||
|
||||
```
|
||||
<alfresco.bomDependencyArtifactId>acs-packaging</alfresco.bomDependencyArtifactId>
|
||||
```
|
||||
|
||||
* Change the Docker ACS image name:
|
||||
|
||||
```
|
||||
<docker.acs.image>alfresco/alfresco-content-repository</docker.acs.image>
|
||||
```
|
||||
|
||||
Changing these parameters instructs the project to use the proper maven dependencies and Docker images.
|
||||
|
||||
Depending on the needs of your project, it will probably be necessary to change the `org.alfresco:alfresco-remote-api` dependency to
|
||||
`org.alfresco:alfresco-enterprise-remote-api` or adding any other enterprise dependency like `org.alfresco:alfresco-enterprise-repository`. In any case,
|
||||
it won't be necessary to include the version of any of these dependencies due to the addition of the BOM dependency in the `dependencyManagement`
|
||||
section of the parent `pom.xml` file.
|
||||
|
||||
## Configuring the Enterprise version
|
||||
|
||||
The configuration of the Enterprise version is straightforward when using the `pom.xml` configuration file stored in the root folder of your project.
|
||||
You'll need to update the following settings in the `pom.xml` file:
|
||||
|
||||
```
|
||||
<alfresco.platform.version>6.0.0.2</alfresco.platform.version>
|
||||
<alfresco.share.version>6.0</alfresco.share.version>
|
||||
```
|
||||
**(confirmation required)**
|
||||
|
||||
Making use of the Alfresco SDK 4.0 it is no longer required the configuration of the Alfresco Surf versions. The inclusion of the BOM and the custom Docker
|
||||
images will take care of that task automatically for you.
|
||||
|
||||
## Purging the project data and running the project
|
||||
|
||||
Once all the previous configuration is done, you only need to purge any possible old data (persistent data from the Docker containers), rebuild and restart
|
||||
the project.
|
||||
|
||||
```
|
||||
$ ./run.sh purge
|
||||
$ ./run.sh build_start
|
||||
```
|
||||
|
||||
If you're using Windows, you'll need to use the `run.bat` script instead of `run.sh`.
|
||||
@ -0,0 +1,118 @@
|
||||
---
|
||||
Title: How to set up Alfresco Transform Service
|
||||
Added: v4.0.0
|
||||
Last reviewed: 2019-01-14
|
||||
---
|
||||
# How to set up Alfresco Transform Service
|
||||
|
||||
By default, the _Alfresco Transform Service_ (from now ATS) is not included in the basic configuration of the projects generated making use of the Alfresco
|
||||
SDK archetypes.
|
||||
|
||||
ATS is only supported in ACS Enterprise and it is distributed as a composition of Docker containers. The docker images required for ATS are available in the
|
||||
Alfresco private docker registry at [Quay.io](https://quay.io/). For more information, see [How to configure private Alfresco Docker registry](enterprise-docker-registry.md).
|
||||
|
||||
In order to properly configure ATS in a project generated using the Alfresco SDK archetypes it is required to execute 2 steps:
|
||||
1. Add the containers that conform ATS to the Docker compose file.
|
||||
2. Configure the properties that are required to properly set up ATS.
|
||||
|
||||
## Adding the new containers
|
||||
|
||||
* Locate the Docker compose file (usually at `PROJECT_ROOT_PATH/docker/docker-compose.yml`) and add the containers that conform ATS (`transform-router`,
|
||||
`alfresco-pdf-renderer`, `imagemagick`, `libreoffice`, `tika`, `shared-file-store` and `activemq`):
|
||||
|
||||
```
|
||||
services:
|
||||
...
|
||||
transform-router:
|
||||
image: quay.io/alfresco/alfresco-transform-router:0.5.0
|
||||
environment:
|
||||
JAVA_OPTS: " -Xms256m -Xmx512m"
|
||||
ACTIVEMQ_URL: "nio://activemq:61616"
|
||||
IMAGEMAGICK_URL: "http://imagemagick:8090"
|
||||
PDF_RENDERER_URL: "http://alfresco-pdf-renderer:8090"
|
||||
LIBREOFFICE_URL: "http://libreoffice:8090"
|
||||
TIKA_URL: "http://tika:8090"
|
||||
FILE_STORE_URL: "http://shared-file-store:8099/alfresco/api/-default-/private/sfs/versions/1/file"
|
||||
links:
|
||||
- activemq
|
||||
alfresco-pdf-renderer:
|
||||
image: quay.io/alfresco/alfresco-pdf-renderer:2.0.8
|
||||
environment:
|
||||
JAVA_OPTS: " -Xms256m -Xmx512m"
|
||||
FILE_STORE_URL: "http://shared-file-store:8099/alfresco/api/-default-/private/sfs/versions/1/file"
|
||||
ports:
|
||||
- 8090:8090
|
||||
imagemagick:
|
||||
image: quay.io/alfresco/alfresco-imagemagick:2.0.8
|
||||
environment:
|
||||
JAVA_OPTS: " -Xms256m -Xmx512m"
|
||||
FILE_STORE_URL: "http://shared-file-store:8099/alfresco/api/-default-/private/sfs/versions/1/file"
|
||||
ports:
|
||||
- 8091:8090
|
||||
libreoffice:
|
||||
image: quay.io/alfresco/alfresco-libreoffice:2.0.8
|
||||
environment:
|
||||
JAVA_OPTS: " -Xms256m -Xmx512m"
|
||||
FILE_STORE_URL: "http://shared-file-store:8099/alfresco/api/-default-/private/sfs/versions/1/file"
|
||||
ports:
|
||||
- 8092:8090
|
||||
tika:
|
||||
image: quay.io/alfresco/alfresco-tika:2.0.8
|
||||
environment:
|
||||
JAVA_OPTS: " -Xms256m -Xmx512m"
|
||||
FILE_STORE_URL: "http://shared-file-store:8099/alfresco/api/-default-/private/sfs/versions/1/file"
|
||||
ports:
|
||||
- 8093:8090
|
||||
shared-file-store:
|
||||
image: alfresco/alfresco-shared-file-store:0.5.1
|
||||
environment:
|
||||
JAVA_OPTS: " -Xms256m -Xmx512m"
|
||||
scheduler.content.age.millis: 86400000
|
||||
scheduler.cleanup.interval: 86400000
|
||||
ports:
|
||||
- 8099:8099
|
||||
volumes:
|
||||
- shared-file-store-volume:/tmp/Alfresco/sfs
|
||||
activemq:
|
||||
image: alfresco/alfresco-activemq:5.15.6
|
||||
ports:
|
||||
- 8161:8161 # Web Console
|
||||
- 5672:5672 # AMQP
|
||||
- 61616:61616 # OpenWire
|
||||
- 61613:61613 # STOMP
|
||||
...
|
||||
```
|
||||
|
||||
* Check that you haven't any port conflict with other services in the Docker compose file.
|
||||
* Add the new volume required for the shared file store (`alfresco/alfresco-shared-file-store`) in the Docker compose file:
|
||||
|
||||
```
|
||||
volumes:
|
||||
...
|
||||
shared-file-store-volume:
|
||||
driver_opts:
|
||||
type: tmpfs
|
||||
device: tmpfs
|
||||
```
|
||||
|
||||
## Adding the required configuration
|
||||
|
||||
* Locate the _Alfresco global properties_ file for docker (usually at `PROJECT_ROOT_PATH/PROJECT_ARTIFACT_ID-platform-docker/src/main/docker/alfresco-global.properties`)
|
||||
and add the ATS configuration properties:
|
||||
|
||||
```
|
||||
# Alfresco Transform Service
|
||||
alfresco-pdf-renderer.url=http://alfresco-pdf-renderer:8090/
|
||||
jodconverter.url=http://libreoffice:8090/
|
||||
img.url=http://imagemagick:8090/
|
||||
tika.url=http://tika:8090/
|
||||
sfs.url=http://shared-file-store:8099/
|
||||
local.transform.service.enabled=true
|
||||
transform.service.enabled=true
|
||||
messaging.broker.url=failover:(nio://activemq:61616)?timeout=3000&jms.useCompression=true
|
||||
```
|
||||
|
||||
* Remove the old value of the property `messaging.broker.url` in the same `alfresco-global.properties` file.
|
||||
|
||||
Once these 2 modifications are done, rebuild and restart all the services (`run.sh/run.bat build_start`) and ACS will use ATS to execute remote transformations
|
||||
asynchronously whenever possible.
|
||||
@ -0,0 +1,20 @@
|
||||
---
|
||||
Title: How to configure private Alfresco Docker registry
|
||||
Added: v3.0.0
|
||||
Last reviewed: 2019-01-15
|
||||
---
|
||||
# How to configure private Alfresco Docker registry
|
||||
|
||||
In order to download the Docker images needed to work with Alfresco Content Services Enterprise Edition it is required to configure the Alfresco private Docker registry
|
||||
hosted at [Quay.io](https://quay.io/).
|
||||
|
||||
The first matter to consider is to ensure that you have credentials for the Alfresco private Docker registry, where the Alfresco images are stored. Customers and partners can
|
||||
request these credentials opening a ticket on the [Alfresco Support Portal](http://support.alfresco.com).
|
||||
|
||||
Once you have suitable credentials, you only need to login your docker installation to the Quay.io Docker registry:
|
||||
|
||||
```
|
||||
$ docker login quay.io
|
||||
```
|
||||
|
||||
At this point you have configured Docker to have access to the Alfresco private Docker registry at [Quay.io](https://quay.io/).
|
||||
@ -0,0 +1,31 @@
|
||||
---
|
||||
Title: How to configure private Alfresco Nexus repository
|
||||
Added: v3.0.0
|
||||
Last reviewed: 2019-01-15
|
||||
---
|
||||
# How to configure private Alfresco Nexus repository
|
||||
|
||||
The first matter to consider is to ensure that you have credentials for the Alfresco Private Repository ([artifacts.alfresco.com](artifacts.alfresco.com)), where the Alfresco artifacts are stored. Enterprise customers and partners can
|
||||
request these credentials opening a ticket on the [Alfresco Support Portal](http://support.alfresco.com).
|
||||
|
||||
Once you have suitable credentials, you need to add support for Alfresco private Maven repository to your configuration. This would typically be done by
|
||||
adding your access credentials to the `settings.xml` contained in your `~/.m2` directory (for Linux and OS X). On Windows this resolves to
|
||||
`C:\Users\<username>\.m2`.
|
||||
|
||||
To do this, load `settings.xml` into your editor and add the following new server configuration in the `<servers>` section:
|
||||
|
||||
```
|
||||
<server>
|
||||
<id>alfresco-private-repository</id>
|
||||
<username>username</username>
|
||||
<password>password</password>
|
||||
</server>
|
||||
```
|
||||
|
||||
You will need to replace the placeholder text with your real username and password as allocated by Alfresco. The id value should not be changed as it
|
||||
is used in the Alfresco SDK project build files to specify the Enterprise artifacts Maven repository.
|
||||
|
||||
It is possible to use encrypted passwords here. See the [official Maven documentation](http://maven.apache.org/guides/mini/guide-encryption.html) for details
|
||||
on how to do this.
|
||||
|
||||
At this point you have configured Maven to have access to the Alfresco Private Repository.
|
||||
BIN
docs/docassets/images/sdk-debug-eclipse-breakpoint.png
Normal file
BIN
docs/docassets/images/sdk-debug-eclipse-breakpoint.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 320 KiB |
BIN
docs/docassets/images/sdk-debug-eclipse-config.png
Normal file
BIN
docs/docassets/images/sdk-debug-eclipse-config.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 113 KiB |
BIN
docs/docassets/images/sdk-debug-eclipse-create.png
Normal file
BIN
docs/docassets/images/sdk-debug-eclipse-create.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 18 KiB |
BIN
docs/docassets/images/sdk-debug-eclipse-launch.png
Normal file
BIN
docs/docassets/images/sdk-debug-eclipse-launch.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 20 KiB |
BIN
docs/docassets/images/sdk-debug-intellij-breakpoint.png
Normal file
BIN
docs/docassets/images/sdk-debug-intellij-breakpoint.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 368 KiB |
BIN
docs/docassets/images/sdk-debug-intellij-config.png
Normal file
BIN
docs/docassets/images/sdk-debug-intellij-config.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 88 KiB |
BIN
docs/docassets/images/sdk-debug-intellij-create.png
Normal file
BIN
docs/docassets/images/sdk-debug-intellij-create.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 6.1 KiB |
BIN
docs/docassets/images/sdk-debug-intellij-launch.png
Normal file
BIN
docs/docassets/images/sdk-debug-intellij-launch.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 7.3 KiB |
BIN
docs/docassets/images/sdk-dev-env-eclipse-import.png
Normal file
BIN
docs/docassets/images/sdk-dev-env-eclipse-import.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 64 KiB |
BIN
docs/docassets/images/sdk-dev-env-eclipse-project.png
Normal file
BIN
docs/docassets/images/sdk-dev-env-eclipse-project.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 102 KiB |
BIN
docs/docassets/images/sdk-dev-env-eclipse-quickfix.png
Normal file
BIN
docs/docassets/images/sdk-dev-env-eclipse-quickfix.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 89 KiB |
BIN
docs/docassets/images/sdk-dev-env-eclipse-warning.png
Normal file
BIN
docs/docassets/images/sdk-dev-env-eclipse-warning.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 94 KiB |
BIN
docs/docassets/images/sdk-dev-env-intellij-finish.png
Normal file
BIN
docs/docassets/images/sdk-dev-env-intellij-finish.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 100 KiB |
BIN
docs/docassets/images/sdk-dev-env-intellij-import.png
Normal file
BIN
docs/docassets/images/sdk-dev-env-intellij-import.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 146 KiB |
BIN
docs/docassets/images/sdk-hellofromjava.png
Normal file
BIN
docs/docassets/images/sdk-hellofromjava.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 43 KiB |
BIN
docs/docassets/images/sdk-hellofromme.png
Normal file
BIN
docs/docassets/images/sdk-hellofromme.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 43 KiB |
BIN
docs/docassets/images/sdk-it-eclipse-results.png
Normal file
BIN
docs/docassets/images/sdk-it-eclipse-results.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 175 KiB |
BIN
docs/docassets/images/sdk-it-eclipse-run.png
Normal file
BIN
docs/docassets/images/sdk-it-eclipse-run.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 203 KiB |
BIN
docs/docassets/images/sdk-it-intellij-results.png
Normal file
BIN
docs/docassets/images/sdk-it-intellij-results.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 467 KiB |
BIN
docs/docassets/images/sdk-it-intellij-run.png
Normal file
BIN
docs/docassets/images/sdk-it-intellij-run.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 260 KiB |
BIN
docs/docassets/images/sdk-jrebel-eclipse-projects.png
Normal file
BIN
docs/docassets/images/sdk-jrebel-eclipse-projects.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 47 KiB |
BIN
docs/docassets/images/sdk-jrebel-eclipse-server.png
Normal file
BIN
docs/docassets/images/sdk-jrebel-eclipse-server.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 42 KiB |
BIN
docs/docassets/images/sdk-jrebel-eclipse-servers.png
Normal file
BIN
docs/docassets/images/sdk-jrebel-eclipse-servers.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 35 KiB |
BIN
docs/docassets/images/sdk-jrebel-intellij-projects.png
Normal file
BIN
docs/docassets/images/sdk-jrebel-intellij-projects.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 24 KiB |
BIN
docs/docassets/images/sdk-jrebel-intellij-server.png
Normal file
BIN
docs/docassets/images/sdk-jrebel-intellij-server.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 32 KiB |
BIN
docs/docassets/images/sdk-jrebel-intellij-servers.png
Normal file
BIN
docs/docassets/images/sdk-jrebel-intellij-servers.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 37 KiB |
202
docs/getting-started.md
Normal file
202
docs/getting-started.md
Normal file
@ -0,0 +1,202 @@
|
||||
---
|
||||
Title: Getting started with Alfresco SDK 4.0
|
||||
Added: v2.1.1
|
||||
Last reviewed: 2019-01-14
|
||||
---
|
||||
# Getting started with Alfresco SDK 4.0
|
||||
|
||||
Use these instructions to get started with using Alfresco SDK 4.0.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
There are a number of software requirements for using Alfresco SDK 4.0.
|
||||
* Java Development Kit (JDK) - Version 11
|
||||
* Maven - Version 3.3
|
||||
* Docker - Latest stable version
|
||||
* JRebel (optional) for hot reloading of web resources, configuration, and classes
|
||||
* HotSwap Agent (optional) for hot reloading of web resources, configuration, and classes
|
||||
|
||||
### Java
|
||||
|
||||
ACS 6.0 is compiled and executed using Java 8, but it is highly recommended to work with ACS 6.1 which uses Java 11.
|
||||
|
||||
1. Download [JDK 11](https://jdk.java.net/11/), unzip it and configure it as the default Java installation.
|
||||
|
||||
2. Verify the installation for both JDK and JRE.
|
||||
|
||||
```
|
||||
$ javac -version
|
||||
javac 11.0.1
|
||||
|
||||
$ java -version
|
||||
openjdk version "11.0.1" 2018-10-16
|
||||
OpenJDK Runtime Environment 18.9 (build 11.0.1+13)
|
||||
OpenJDK 64-Bit Server VM 18.9 (build 11.0.1+13, mixed mode)
|
||||
```
|
||||
|
||||
3. Make sure JAVA_HOME is setup correctly, so other tools like Maven will use the correct version.
|
||||
|
||||
```
|
||||
$ env|grep JAVA_HOME
|
||||
JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-11.0.1.jdk/Contents/Home
|
||||
```
|
||||
|
||||
### Maven
|
||||
|
||||
Alfresco recommends that you keep up-to-date with all the Maven releases. Linux distributions and package managers tend to bundle older releases and this is
|
||||
the most common pitfall.
|
||||
|
||||
Alfresco SDK 4.0 requires Maven 3.3.0+, but you are recommended to download the latest version.
|
||||
|
||||
1. Download and install [Apache Maven](https://maven.apache.org/download.cgi) and make sure it is configured correctly on your path.
|
||||
|
||||
2. Verify the installation.
|
||||
|
||||
```
|
||||
$ mvn -v
|
||||
Apache Maven 3.3.9 (bb52d8502b132ec0a5a3f4c09453c07478323dc5; 2015-11-10T17:41:47+01:00)
|
||||
Maven home: /usr/local/Cellar/maven/3.3.9/libexec
|
||||
Java version: 11.0.1, vendor: Oracle Corporation
|
||||
Java home: /Library/Java/JavaVirtualMachines/jdk-11.0.1.jdk/Contents/Home
|
||||
Default locale: en_ES, platform encoding: UTF-8
|
||||
OS name: "mac os x", version: "10.13.4", arch: "x86_64", family: "mac"
|
||||
```
|
||||
|
||||
### Docker
|
||||
|
||||
Alfresco recommends that you keep up-to-date with all the Docker releases. If you're using an older version of Windows or Mac you'll have to use
|
||||
[Docker Toolbox](https://docs.docker.com/toolbox/) which has some known issues.
|
||||
|
||||
1. Download and install [Docker](https://docs.docker.com/install/).
|
||||
|
||||
2. Verify the installation of Docker.
|
||||
|
||||
```
|
||||
$ docker -v
|
||||
Docker version 18.06.1-ce, build e68fc7a
|
||||
```
|
||||
|
||||
3. [Docker Compose](https://docs.docker.com/compose/install/) is included as part of some Docker installers. If it's not part of your installation, then
|
||||
install it separately after you've installed Docker.
|
||||
|
||||
4. Verify the installation of Docker Compose.
|
||||
|
||||
```
|
||||
$ docker-compose -v
|
||||
docker-compose version 1.22.0, build f46880f
|
||||
```
|
||||
|
||||
## Generate your project from the archetypes
|
||||
|
||||
1. After you've successfully configured Java and Maven, it's time to generate your project.
|
||||
|
||||
```
|
||||
mvn archetype:generate -Dfilter=org.alfresco:
|
||||
```
|
||||
|
||||
You'll be prompted to select the archetype you want. The previously available archetypes, alfresco-amp-archetype and share-amp-archetype will still show up
|
||||
as an option, however these archetypes are not part of Alfresco SDK 4.0.
|
||||
|
||||
Attention: You'll need double quotes around the filter part if you are using Windows Powershell: mvn archetype:generate "-Dfilter=org.alfresco:".
|
||||
|
||||
The output looks something like this:
|
||||
|
||||
```
|
||||
[INFO] Generating project in Interactive mode
|
||||
[INFO] No archetype defined. Using maven-archetype-quickstart (org.apache.maven.archetypes:maven-archetype-quickstart:1.0)
|
||||
Choose archetype:
|
||||
1: remote -> org.alfresco.maven.archetype:alfresco-platform-jar-archetype (Sample project with full support for lifecycle and rapid development of Platform/Repository JARs and AMPs (Alfresco Module Packages))
|
||||
2: remote -> org.alfresco.maven.archetype:alfresco-share-jar-archetype (Share project with full support for lifecycle and rapid development of JARs and AMPs (Alfresco Module
|
||||
Packages))
|
||||
3: remote -> org.alfresco.maven.archetype:alfresco-allinone-archetype (Sample multi-module project for All-in-One development on the Alfresco platform. Includes modules for Platform/Repository JAR and Share JAR)
|
||||
...
|
||||
```
|
||||
|
||||
2. Select one of the following archetypes:
|
||||
|
||||
* `org.alfresco.maven.archetype:alfresco-allinone-archetype`
|
||||
* `org.alfresco.maven.archetype:alfresco-platform-jar-archetype`
|
||||
* `org.alfresco.maven.archetype:alfresco-share-jar-archetype`
|
||||
|
||||
3. Choose the latest version, such as 4.0.0.
|
||||
|
||||
```
|
||||
Choose org.alfresco.maven.archetype:alfresco-allinone-archetype version:
|
||||
1: 2.0.0-beta-1
|
||||
2: 2.0.0-beta-2
|
||||
3: 2.0.0-beta-3
|
||||
4: 2.0.0-beta-4
|
||||
5: 2.0.0
|
||||
6: 2.1.0
|
||||
7: 2.1.1
|
||||
8: 2.2.0
|
||||
9: 3.0.0
|
||||
10: 3.0.1
|
||||
11: 4.0.0
|
||||
```
|
||||
|
||||
4. Next you will be prompted for additional values, like groupId, artifactId, and package, as shown below:
|
||||
|
||||
```
|
||||
Define value for property 'groupId':
|
||||
Define value for property 'artifactId':
|
||||
[INFO] Using property: version = 1.0-SNAPSHOT
|
||||
Define value for property 'package':
|
||||
```
|
||||
|
||||
5. After you have specified the information according to your project, a final confirmation will appear.
|
||||
|
||||
```
|
||||
Confirm properties configuration:
|
||||
groupId: com.acme
|
||||
artifactId: my-all-in-one
|
||||
version: 1.0-SNAPSHOT
|
||||
package: com.acme
|
||||
Y: :
|
||||
```
|
||||
|
||||
6. Press **Y** and then press **Enter**.
|
||||
|
||||
If everything has been configured correctly, you should see something similar to this:
|
||||
|
||||
```
|
||||
[INFO] ----------------------------------------------------------------------------
|
||||
[INFO] Using following parameters for creating project from Archetype: alfresco-allinone-archetype:4.0.0-SNAPSHOT
|
||||
[INFO] ----------------------------------------------------------------------------
|
||||
[INFO] Parameter: groupId, Value: com.acme
|
||||
[INFO] Parameter: artifactId, Value: my-all-in-one
|
||||
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
|
||||
[INFO] Parameter: package, Value: com.acme
|
||||
[INFO] Parameter: packageInPathFormat, Value: com/acme
|
||||
[INFO] Parameter: package, Value: com.acme
|
||||
[INFO] Parameter: groupId, Value: com.acme
|
||||
[INFO] Parameter: artifactId, Value: my-all-in-one
|
||||
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
|
||||
[INFO] Parent element not overwritten in /Users/Alfresco/my-all-in-one/my-all-in-one-platform-jar/pom.xml
|
||||
[INFO] Parent element not overwritten in /Users/Alfresco/my-all-in-one/my-all-in-one-share-jar/pom.xml
|
||||
[INFO] Parent element not overwritten in /Users/Alfresco/my-all-in-one/integration-tests/pom.xml
|
||||
[INFO] Parent element not overwritten in /Users/Alfresco/my-all-in-one/my-all-in-one-platform-docker/pom.xml
|
||||
[INFO] Parent element not overwritten in /Users/Alfresco/my-all-in-one/my-all-in-one-share-docker/pom.xml
|
||||
[INFO] Executing META-INF/archetype-post-generate.groovy post-generation script
|
||||
[INFO] Project created from Archetype in dir: /Users/Alfresco/my-all-in-one
|
||||
[INFO] ------------------------------------------------------------------------
|
||||
[INFO] BUILD SUCCESS
|
||||
[INFO] ------------------------------------------------------------------------
|
||||
[INFO] Total time: 04:11 min
|
||||
[INFO] Finished at: 2019-01-10T16:21:46+01:00
|
||||
[INFO] Final Memory: 17M/1024M
|
||||
[INFO] ------------------------------------------------------------------------
|
||||
```
|
||||
|
||||
7. You have successfully generated your first SDK 4.0 project.
|
||||
|
||||
Inside the project, you will find the `run.bat` and `run.sh` scripts. These are convenience scripts for you to quickly compile / test / run your project.
|
||||
|
||||
In the terminal window, use:
|
||||
* `./run.sh build_start` for Mac OS X or Linux.
|
||||
* `run.bat build_start` for Windows.
|
||||
|
||||
If this is the first time you are doing this, it will take a while for Maven to download all the required dependencies and for Docker to download all the
|
||||
required images.
|
||||
|
||||
For more information about how to work with the projects, please visit [Working with generated projects](working-with-generated-projects/README.md).
|
||||
132
docs/mvn-archetypes.md
Normal file
132
docs/mvn-archetypes.md
Normal file
@ -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](working-with-generated-projects/structure-aio.md).
|
||||
|
||||
### 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](working-with-generated-projects/structure-platform.md).
|
||||
|
||||
### 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](working-with-generated-projects/structure-share.md).
|
||||
|
||||
### 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.
|
||||
8
docs/setting-up-your-development-environment/README.md
Normal file
8
docs/setting-up-your-development-environment/README.md
Normal file
@ -0,0 +1,8 @@
|
||||
---
|
||||
Title: Setting up your development environment
|
||||
Added: v3.0.0
|
||||
Last reviewed: 2019-01-17
|
||||
---
|
||||
# Setting up your development environment
|
||||
|
||||
The Maven Alfresco SDK is designed to work well with [Eclipse](https://www.eclipse.org/) and [IntelliJ IDEA](https://www.jetbrains.com/idea/).
|
||||
@ -0,0 +1,54 @@
|
||||
---
|
||||
Title: Setting up your development environment using Eclipse
|
||||
Added: v3.0.0
|
||||
Last reviewed: 2019-01-14
|
||||
---
|
||||
# Setting up your development environment using Eclipse
|
||||
|
||||
The Maven Alfresco SDK is designed to work well with Eclipse. This support includes the ability to import existing Alfresco projects created using the
|
||||
Alfresco SDK.
|
||||
|
||||
Here we assume you already have an Eclipse installation up and running, together with an available Alfresco project created using the Alfresco SDK. If you
|
||||
don't have a project already, follow the steps in [Getting started with Alfresco SDK 4.0](../getting-started.md) to learn how to quickly generate it in a few
|
||||
easy steps.
|
||||
|
||||
## Importing the Alfresco project into Eclipse
|
||||
|
||||
1. Starting from Eclipse, select `File > Import > Maven > Existing Maven Projects` from the main menu to import the Alfresco project.
|
||||
|
||||
|
||||
|
||||
2. Click `Next` then browse to the root of the Alfresco project.
|
||||
|
||||
|
||||
|
||||
3. Click `Finish` to start importing the project into Eclipse.
|
||||
|
||||
Before completing the import, Eclipse checks the completeness of the local Maven repository. If you already have a local repository that includes all the
|
||||
required dependencies, this task will finish relatively quickly. Otherwise, be patient and wait until the downloads are completed (it can take some time).
|
||||
|
||||
Once the import is complete, a warning message may be displayed.
|
||||
|
||||
|
||||
|
||||
4. Click `Resolve All Later` to complete the import task.
|
||||
|
||||
5. Check the Markers tab in the bottom panel, where you may see some Maven problems. Expand the list and right click on a item with an error, then select
|
||||
`Quick Fix` and mark as shown.
|
||||
|
||||
|
||||
|
||||
6. Click `Finish` to confirm the fix.
|
||||
|
||||
You may be asked to confirm your selection.
|
||||
|
||||
7. Repeat the fix for all similar issues you have. Note that these issues really depend on the archetype you used to generate the project.
|
||||
|
||||
Once done, you may see an error with description: Project configuration is not up-to-date with pom.xml.
|
||||
|
||||
8. To fix this, right click one of the Alfresco projects and select `Maven > Update Project`, ensure all the Alfresco projects and sub-projects are selected,
|
||||
and then click `OK`.
|
||||
|
||||
Once this is done, the project is successfully imported in Eclipse.
|
||||
|
||||
If you want more detail about how to work with the project, please visit [Working with generated projects](../working-with-generated-projects/README.md).
|
||||
@ -0,0 +1,28 @@
|
||||
---
|
||||
Title: Setting up your development environment using Intellij IDEA
|
||||
Added: v3.0.0
|
||||
Last reviewed: 2019-01-14
|
||||
---
|
||||
# Setting up your development environment using Intellij IDEA
|
||||
|
||||
The Maven Alfresco SDK is designed to work well with Eclipse. This support includes the ability to import existing Alfresco projects created using the
|
||||
Alfresco SDK.
|
||||
|
||||
Here we assume you already have an Eclipse installation up and running, together with an available Alfresco project created using the Alfresco SDK. If you
|
||||
don't have a project already, follow the steps in [Getting started with Alfresco SDK 4.0](../getting-started.md) to learn how to quickly generate it in a few
|
||||
easy steps.
|
||||
|
||||
## Importing the Alfresco project into Intellij IDEA
|
||||
|
||||
1. Starting from IntelliJ IDEA, select `File > Open` from the main menu to open the Alfresco project. Alternatively, select `Import Project` if you're running
|
||||
IntelliJ IDEA for the first time in your development environment.
|
||||
|
||||
|
||||
|
||||
2. After the project is imported, you will see a window similar to the following:
|
||||
|
||||
|
||||
|
||||
Once this is done, the project is successfully imported in IntelliJ IDEA.
|
||||
|
||||
If you want more detail about how to work with the project, please visit [Working with generated projects](../working-with-generated-projects/README.md).
|
||||
148
docs/troubleshooting.md
Normal file
148
docs/troubleshooting.md
Normal file
@ -0,0 +1,148 @@
|
||||
---
|
||||
Title: Troubleshooting
|
||||
Added: v3.0.0
|
||||
Last reviewed: 2019-01-14
|
||||
---
|
||||
# Troubleshooting
|
||||
|
||||
This article describes a list of common issues with the projects generated from the Alfresco SDK 4.0 archetypes and the way to troubleshoot them.
|
||||
|
||||
* [Incorrect JDK version](#incorrect-jdk-version)
|
||||
* [Containers synchronization](#containers-synchronization)
|
||||
* [Ports conflict](#ports-conflict)
|
||||
|
||||
## Incorrect JDK version
|
||||
|
||||
### Problem
|
||||
|
||||
The ACS container is not starting properly and it is showing Java compatibility errors in the logs:
|
||||
|
||||
```
|
||||
org.springframework.beans.factory.CannotLoadBeanClassException:
|
||||
Error loading class [com.example.platformsample.Demo] for bean with name 'com.example.Demo' defined in class path resource
|
||||
[alfresco/module/sample-project-platform-jar/context/service-context.xml]:
|
||||
problem with class file or dependent class; nested exception is java.lang.UnsupportedClassVersionError:
|
||||
com/example/platformsample/Demo has been compiled by a more recent version of the Java Runtime (class file version 55.0),
|
||||
this version of the Java Runtime only recognizes class file versions up to 52.0 (unable to load class [com.example.platformsample.Demo])
|
||||
```
|
||||
|
||||
This error represents that the source code was compiled using the wrong version of the JDK. This issue can happen if the generated project is compiled using
|
||||
JDK 11 and it is deployed in an ACS 6.0 container (which uses JRE 8).
|
||||
|
||||
### Solution
|
||||
|
||||
To solve this issue you can follow several approaches:
|
||||
* Compile the project using a JDK version lower than 11 (and equal to or newer than 8).
|
||||
* Remove the `java11` profile in the `pom.xml` file of the base project (this is not recommended if you plan to move to ACS 6.1 in the future).
|
||||
* Move to ACS 6.1+. This is highly recommended due to the fact that it uses JRE 11 (JDK 8 has already reached its end of support time).
|
||||
|
||||
## Containers synchronization
|
||||
|
||||
### Problem
|
||||
|
||||
ACS depends on the readiness of the database in order to start properly. If the database is not ready when ACS reaches the startup phase that requires it, then
|
||||
it fails showing error messages in the log:
|
||||
|
||||
```
|
||||
sample-project-acs_1 | Jan 10, 2019 10:58:06 AM org.postgresql.core.v3.ConnectionFactoryImpl log
|
||||
sample-project-acs_1 | WARNING: IOException occurred while connecting to sample-project-postgres:5432
|
||||
sample-project-acs_1 | java.net.UnknownHostException: sample-project-postgres
|
||||
sample-project-acs_1 | at java.base/java.net.AbstractPlainSocketImpl.connect(AbstractPlainSocketImpl.java:220)
|
||||
sample-project-acs_1 | at java.base/java.net.SocksSocketImpl.connect(SocksSocketImpl.java:403)
|
||||
sample-project-acs_1 | at java.base/java.net.Socket.connect(Socket.java:591)
|
||||
sample-project-acs_1 | at org.postgresql.core.PGStream.<init>(PGStream.java:69)
|
||||
...
|
||||
sample-project-acs_1 | 10-Jan-2019 10:58:06.281 SEVERE [localhost-startStop-1] org.postgresql.Driver.connect Connection error:
|
||||
sample-project-acs_1 | org.postgresql.util.PSQLException: The connection attempt failed.
|
||||
sample-project-acs_1 | at org.postgresql.core.v3.ConnectionFactoryImpl.openConnectionImpl(ConnectionFactoryImpl.java:259)
|
||||
sample-project-acs_1 | at org.postgresql.core.ConnectionFactory.openConnection(ConnectionFactory.java:49)
|
||||
sample-project-acs_1 | at org.postgresql.jdbc.PgConnection.<init>(PgConnection.java:195)
|
||||
...
|
||||
```
|
||||
|
||||
The projects generated using the Alfresco SDK archetypes are configured in a way that the ACS container _depends on_ the database container (PostgreSQL).
|
||||
|
||||
```
|
||||
services:
|
||||
sample-project-acs:
|
||||
image: alfresco-content-services-sample-project:development
|
||||
...
|
||||
depends_on:
|
||||
- sample-project-postgres
|
||||
sample-project-postgres:
|
||||
image: postgres:9.6
|
||||
...
|
||||
```
|
||||
|
||||
The problem is Docker compose only ensures that the dependant container will be started before the one that declares the dependency. But that doesn't ensure
|
||||
that the PostgreSQL (or any other database) service will be ready when the ACS script reaches the point in which the database is required.
|
||||
|
||||
Usually, the database service starts before ACS requires it, but there are some infrequent cases (an environment with low resources or high load) in which this
|
||||
synchronization issue appears.
|
||||
|
||||
### Solution
|
||||
|
||||
In these cases, you can follow the [recommendation in the official Docker documentation](https://docs.docker.com/compose/startup-order/), which is to use a
|
||||
scripting sync solution like _wait-for-it_ or _dockerize_.
|
||||
|
||||
Let's see how you can configure the ACS container to use [wait-for-it](https://github.com/vishnubob/wait-for-it) to wait for the database service to be ready
|
||||
to accept connections:
|
||||
|
||||
1. Download the last version of the [wait-for-it](https://github.com/vishnubob/wait-for-it) bash script and save it into the folder
|
||||
`PROJECT_ARTIFACT_ID-platform-docker/src/main/docker`.
|
||||
|
||||
2. Modify the file `PROJECT_ARTIFACT_ID-platform-docker/src/main/docker/Dockerfile` to include the addition of the script to the ACS container and granting
|
||||
execution permission to it.
|
||||
|
||||
```
|
||||
# Copy wait-for-it.sh script to wait for other services
|
||||
COPY wait-for-it.sh /tmp/wait-for-it.sh
|
||||
RUN chmod +x /tmp/wait-for-it.sh
|
||||
```
|
||||
|
||||
4. Modify the file `docker/docker-compose.yml` to change the ACS container command to use the _wait-for-it_ script to wait for the PostgreSQL service to be
|
||||
ready.
|
||||
|
||||
```
|
||||
sample-project-acs:
|
||||
image: alfresco-content-services-sample-project:development
|
||||
build:
|
||||
dockerfile: ./Dockerfile
|
||||
context: ../../../sample-project-platform-docker/target
|
||||
environment:
|
||||
CATALINA_OPTS: "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=0.0.0.0:8888"
|
||||
command: ["/tmp/wait-for-it.sh", "sample-project-postgres:5432", "--", "catalina.sh", "run"]
|
||||
ports:
|
||||
- "${acs.port}:8080"
|
||||
- "${acs.debug.port}:8888"
|
||||
```
|
||||
|
||||
With this configuration in place, when the project is rebuilt and restarted the ACS container will wait for the database service to be ready.
|
||||
|
||||
## Ports conflict
|
||||
|
||||
### Problem
|
||||
|
||||
The docker-based development environment started by a project generated using the Alfresco SDK archetypes exposes a set of different ports to the hosted
|
||||
machine (i.e. ACS http port, ACS debug port or PostgreSQL port).
|
||||
|
||||
If one of these ports is already in use in the hosted machine (by another service) when you start the development environment, then the startup process will fail
|
||||
and the container that wanted to expose the busy port won't start.
|
||||
|
||||
### Solution
|
||||
|
||||
The docker compose file under `docker/docker-compose.yml` is the source file that, in the compile phase of the project, will be filtered by the
|
||||
`maven-resource-plugin` in order to produce the final copy of the docker compose file.
|
||||
|
||||
That allows you to modify the number of the exposed ports through maven properties in the `pom.xml` file of the main project.
|
||||
|
||||
```
|
||||
<!-- Environment configuration properties -->
|
||||
<share.port>8180</share.port>
|
||||
<share.debug.port>9898</share.debug.port>
|
||||
<acs.port>8080</acs.port>
|
||||
<acs.debug.port>8888</acs.debug.port>
|
||||
<postgres.port>5555</postgres.port>
|
||||
```
|
||||
|
||||
That way, if you face a port conflict, you only need to change the port in the corresponding maven property and rebuilt and restart the project.
|
||||
58
docs/whats-new.md
Normal file
58
docs/whats-new.md
Normal file
@ -0,0 +1,58 @@
|
||||
---
|
||||
Title: What's new?
|
||||
Added: v2.1.1
|
||||
Last reviewed: 2019-01-17
|
||||
---
|
||||
# What's new?
|
||||
|
||||
Alfresco SDK 4.0 brings some changes oriented to assist the way the customizations are built, packaged, run and tested for Alfresco Content Services 6 and
|
||||
Alfresco Share 6.
|
||||
|
||||
This is a mayor release oriented to support Alfresco 6, so it is not compatible with previous versions of the SDK.
|
||||
|
||||
## Embracing containers and Docker
|
||||
|
||||
The main change included in SDK 4.0 is the addition of container technologies. Specifically, the new SDK is highly based on [Docker](https://www.docker.com/)
|
||||
and [Docker compose](https://docs.docker.com/compose/) to offer a solution aligned with the architectural decisions made in Alfresco for version 6: moving
|
||||
towards microservices-oriented solutions.
|
||||
|
||||
Working with Docker images gives the developers the opportunity to easily customise the deployment of the local environment to adapt it to their requirements.
|
||||
Adding, removing and configuring services in the environment is as easy as modifying the Docker compose descriptor file.
|
||||
|
||||
## Support for Java 11
|
||||
|
||||
[Java 11](https://openjdk.java.net/projects/jdk/11/) is the next Long Term Support (LTS) version that provides support for 3 years. Alfresco 6.1 already offers
|
||||
support for this version of the Java platform.
|
||||
|
||||
Alfresco SDK 4.0 has been modified to add support for Java 11 as well. This way, if you're working as a developer in customisations for Alfresco 6.1 you must
|
||||
now use SDK 4.0 + JDK 11 to work on them. The Apache Maven plugins included in the archetypes has been updated to avoid any issue with Java 11.
|
||||
|
||||
## Easy dependency configuration
|
||||
|
||||
The configuration of the Maven dependency management has been greatly improved thanks to the addition of a _bill of materials_ (BOM).
|
||||
|
||||
The inclusion of the BOM dependency in the `dependencyManagement` section of the `pom.xml` file of the projects generated using the archetypes imports all
|
||||
artifacts in the selected Alfresco platform version. It is still needed to define dependencies in the POM files, but the version can be omitted as it's
|
||||
enforced by this `dependencyManagement`.
|
||||
|
||||
That incredibly eases the management of the versions of the different Alfresco platform's dependencies required in a customisation project.
|
||||
|
||||
## Alfresco Maven Plugin no longer needed
|
||||
|
||||
Alfresco SDK 4.0 manages the lifecycle of the generated projects making use of proper [utility scripts](working-with-generated-projects/README.md#run-script)
|
||||
(`run.sh` / `run.bat`). That avoids the need of using the Alfresco Maven Plugin and eases the process to modify the lifecycle of the customisation projects.
|
||||
|
||||
If a development team has straightforward requirements and doesn't want to worry about the complexity of working with containers, it can use the utility scripts
|
||||
as they are. But, if any development team has a requirement or a development process that requires a customisation in the project development lifecycle, it is
|
||||
easy to modify the utility scripts, the Docker files or the Docker compose descriptor to adapt the SDK projects to their needs.
|
||||
|
||||
The Alfresco Maven Plugin is only required in those cases in which it is required to package the customisation project as an AMP. For more information about
|
||||
how to work with AMPs, please visit [Working with AMPs](advanced-topics/amps.md).
|
||||
|
||||
## Integration testing
|
||||
|
||||
The integration tests and the mechanisms to execute them in an Alfresco Content Service instance remains the same as in the previous version of the SDK.
|
||||
|
||||
However, the inclusion of Docker and the utility scripts provides a different perspective about the environment on which the integration tests are executed.
|
||||
In this version, the integration tests are run against the dockerised environment defined using Docker and Docker compose. By doing so, the integration test
|
||||
environment can be more similar to a real one, including whatever other service is required for a full featured integration test execution.
|
||||
53
docs/working-with-generated-projects/README.md
Normal file
53
docs/working-with-generated-projects/README.md
Normal file
@ -0,0 +1,53 @@
|
||||
---
|
||||
Title: Working with generated projects
|
||||
Added: v3.0.0
|
||||
Last reviewed: 2019-01-15
|
||||
---
|
||||
# Working with generated projects
|
||||
|
||||
After generating a project using one of the Alfresco SDK 4.0 Maven archetypes, it is important to know how to build / run / test these projects.
|
||||
|
||||
The Alfresco Platform 6 deployment architecture is highly based on container technologies, specifically in
|
||||
[Docker](http://docs.alfresco.com/6.0/concepts/master-deploy.html). Due to that, the projects generated using the Alfresco SDK 4.0 archetypes set up their
|
||||
local environment making an intensive use of Docker and Docker compose technologies.
|
||||
|
||||
If you're not familiar with 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 you 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 a utility script to work with the project. This script is `run.sh` for Unix systems
|
||||
and `run.bat` for Windows systems.
|
||||
|
||||
The execution of this script must be followed by a parameter that dictates the task to be executed in the project. The list of available tasks is:
|
||||
|
||||
Task | Description
|
||||
--- | ---
|
||||
`build_start` | Build the whole project, recreate the ACS and Share docker images, start the dockerised environment composed by ACS, Share, ASS and PostgreSQL and tail the logs of all the containers.
|
||||
`start` | Start the dockerised environment without building the project and tail the logs of all the containers.
|
||||
`stop` | Stop the dockerised environment.
|
||||
`purge` | Stop the dockerised environment and delete all the persistent data (docker volumes).
|
||||
`tail` | Tail the logs of all the containers.
|
||||
`reload_share` | Build the Share module, recreate the Share docker image and restart the Share container (not available in the Alfresco Platform JAR archetype).
|
||||
`reload_acs` | Build the ACS module, recreate the ACS docker image and restart the ACS container (only available in the All-In-One archetype).
|
||||
`build_test` | Build the whole project, recreate the ACS and Share docker images, start the dockerised environment, execute the integration tests from the `integration-tests` module and stop the environment.
|
||||
`test` | Execute the integration tests (the environment must be already started).
|
||||
|
||||
This utility script uses `mvn`, `docker` and `docker-compose` commands, so make sure you have properly installed Maven, Docker and Docker compose and you have
|
||||
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.
|
||||
254
docs/working-with-generated-projects/structure-aio.md
Normal file
254
docs/working-with-generated-projects/structure-aio.md
Normal file
@ -0,0 +1,254 @@
|
||||
---
|
||||
Title: All-In-One project structure
|
||||
Added: v3.0.0
|
||||
Last reviewed: 2019-01-15
|
||||
---
|
||||
# All-In-One project structure
|
||||
|
||||
This page provides 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 `<artefactId-platform-docker>`) 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 `<artefactId-platform-jar>`) contains a sub-project entirely dedicated to the customization of the
|
||||
Alfresco Content Services Repository.
|
||||
* `my-all-in-one-project-share-docker` (typically named `<artefactId-share-docker>`) 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 `<artefactId-share-jar>`) 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 folder
|
||||
|
||||
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](README.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 `<artefactId-platform-jar>`) 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/<groupId>...` | 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/<artifactId>` | 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/<groupId>...` | 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 `<artefactId-platform-docker>`) 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 `<artefactId-share-jar>`) 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/<groupId>...` | 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/<artifactId>` | 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).
|
||||
`src/test/java/<groupId>...` | 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-share-docker
|
||||
|
||||
Below is a description of the content in the `my-all-in-one-project-share-docker` (typically named `<artefactId-share-docker>`) 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.
|
||||
|
||||
## integration-tests
|
||||
|
||||
Below is a description of the content in the `integration-tests` sub-project. This sub-project contains all the source code and resources needed to run the integration tests.
|
||||
|
||||
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/java/<groupId>...` | 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. The folder is empty by default.
|
||||
`src/test/java/<groupId>...` | 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 in general related to tests. By default you can find three different tests related to content modelling, custom components, and web scripts.
|
||||
117
docs/working-with-generated-projects/structure-platform.md
Normal file
117
docs/working-with-generated-projects/structure-platform.md
Normal file
@ -0,0 +1,117 @@
|
||||
---
|
||||
Title: Platform JAR project structure
|
||||
Added: v3.0.0
|
||||
Last reviewed: 2019-01-15
|
||||
---
|
||||
# Platform JAR project structure
|
||||
|
||||
This page provides a detailed description of the Platform JAR project, including the project structure and folder content.
|
||||
|
||||
Now that you know what a Platform JAR project is, let’s introduce the structure of the project, once it is created using the
|
||||
`org.alfresco.maven.archetype:alfresco-platform-jar-archetype`.
|
||||
|
||||
Below is an example directory structure of a Platform JAR created with `com.example` as `groupId` and `my-platform-jar-project` as `artifactId`.
|
||||
|
||||
```
|
||||
my-platform-jar-project
|
||||
├── pom.xml
|
||||
├── README.md
|
||||
├── run.bat
|
||||
├── run.sh
|
||||
├── docker
|
||||
| └── docker-compose.yml
|
||||
└── src
|
||||
├── main
|
||||
│ ├── assembly
|
||||
│ │ ├── amp.xml
|
||||
│ │ ├── file-mapping.properties
|
||||
│ │ └── web
|
||||
│ │ └── README.md
|
||||
│ ├── docker
|
||||
│ │ ├── alfresco-global.properties
|
||||
│ │ ├── dev-log4j.properties
|
||||
│ │ ├── disable-webscript-caching-context.xml
|
||||
│ │ ├── Dockerfile
|
||||
│ │ ├── hotswap-agent.properties
|
||||
│ │ └── license
|
||||
│ │ └── 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-platform-jar-project
|
||||
│ │ ├── 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
|
||||
```
|
||||
|
||||
From a high level standpoint, we can describe the content of the project as follows:
|
||||
* `my-platform-jar-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`).
|
||||
* `src` contains the source code, tests, configurations, settings and resources that are entirely dedicated to the customization of the Alfresco Content
|
||||
Services Repository.
|
||||
|
||||
After this brief introduction of the Platform JAR project, let’s focus on the content of the folders.
|
||||
|
||||
## Project root folder
|
||||
|
||||
Below is a description of the files in the root of the project (in this case, `my-platform-jar-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](README.md).
|
||||
`pom.xml` | This XML file contains information about the project and configuration details used by Apache Maven to build the project.
|
||||
`README.md` | File in Markdown format containing the documentation for the project.
|
||||
|
||||
## `src` folder
|
||||
|
||||
Below is a description of the content in the `src` folder. This folder contains the source code, tests, configuration, settings, and resources entirely
|
||||
dedicated to the customization of the Alfresco Content Services Repository.
|
||||
|
||||
Content | Description
|
||||
--- | ---
|
||||
`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/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.
|
||||
`src/main/java/<groupId>...` | 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/<artifactId>` | 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/<groupId>...` | 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.
|
||||
112
docs/working-with-generated-projects/structure-share.md
Normal file
112
docs/working-with-generated-projects/structure-share.md
Normal file
@ -0,0 +1,112 @@
|
||||
---
|
||||
Title: Share JAR project structure
|
||||
Added: v3.0.0
|
||||
Last reviewed: 2019-01-15
|
||||
---
|
||||
# Share JAR project structure
|
||||
|
||||
The following page provides a detailed description of the Share client JAR project, including the project structure and folder content.
|
||||
|
||||
Now that you know what a Share JAR project is, let’s introduce the structure of the project, once it is created using the
|
||||
`org.alfresco.maven.archetype:alfresco-share-jar-archetype`.
|
||||
|
||||
Below is an example directory structure of a Share JAR created with `com.example` as `groupId` and `my-share-jar-project` as `artifactId`.
|
||||
|
||||
```
|
||||
my-share-jar-project
|
||||
├── pom.xml
|
||||
├── README.md
|
||||
├── run.bat
|
||||
├── run.sh
|
||||
└── src
|
||||
├── main
|
||||
│ ├── assembly
|
||||
│ │ ├── amp.xml
|
||||
│ │ ├── file-mapping.properties
|
||||
│ │ └── web
|
||||
│ │ └── README.md
|
||||
│ ├── docker
|
||||
│ │ ├── Dockerfile
|
||||
│ │ ├── hotswap-agent.properties
|
||||
│ │ ├── log4j.properties
|
||||
│ │ └── share-config-custom.xml
|
||||
│ ├── java
|
||||
│ │ └── com
|
||||
│ │ └── example
|
||||
│ └── resources
|
||||
│ ├── alfresco
|
||||
│ │ ├── module
|
||||
│ │ │ └── my-share-jar-project
|
||||
│ │ │ └── module.properties
|
||||
│ │ └── web-extension
|
||||
│ │ ├── messages
|
||||
│ │ │ └── my-share-jar-project.properties
|
||||
│ │ ├── my-share-jar-project-slingshot-application-context.xml
|
||||
│ │ ├── site-data
|
||||
│ │ │ └── extensions
|
||||
│ │ │ └── my-share-jar-project-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-share-jar-project
|
||||
│ │ └── 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-platform-jar-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`).
|
||||
* `src` contains the source code, tests, configurations, settings and resources that are entirely dedicated to the customization of the Alfresco Share client.
|
||||
|
||||
After this brief introduction of the Platform JAR project, let’s focus on the content of the folders.
|
||||
|
||||
## Project root folder
|
||||
|
||||
Below is a description of the files in the root of the project (in this case, `my-share-jar-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](README.md).
|
||||
`pom.xml` | This XML file contains information about the project and configuration details used by Apache Maven to build the project.
|
||||
`README.md` | File in Markdown format containing the documentation for the project.
|
||||
|
||||
## `src` folder
|
||||
|
||||
Below is a description of the content in the `src` folder, which contains the source code, tests, configuration, settings, and resources entirely dedicated to
|
||||
the customization of the Alfresco Share client.
|
||||
|
||||
Content | Description
|
||||
--- | ---
|
||||
`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/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.
|
||||
`src/main/java/<groupId>...` | 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/<artifactId>` | 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/6.0/concepts/dev-extensions-share-configuration.html).
|
||||
`src/test/java/<groupId>...` | 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.
|
||||
Loading…
x
Reference in New Issue
Block a user