inteligr8/alfresco-sdk
1
0
Fork 0
mirror of https://github.com/Alfresco/alfresco-sdk.git synced 2025-07-31 17:39:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documentation - Reorganise documentation content

Browse Source 
Reorganise the documentation content to fix the required folder structure
and file naming for the migration to ABN.
This commit is contained in:
Jose Luis Osorno
2019-01-17 11:32:21 +01:00
parent 0027ef3ec4
commit ccee83f92d
49 changed files with 67 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

234
docs/advanced-topics/amps.md Normal file
View File

@@ -0,0 +1,234 @@
---
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 module in case of an All-In-One project.
Here is an example of how to install Florian Maul's Javascript Console.
```
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 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-jar</artifactId>
<name>Alfresco Platform/Repository JAR Module</name>
<description>Platform/Repo JAR Module (to be included in the alfresco.war) - part of AIO - SDK 4.0
</description>
<packaging>jar</packaging>
<parent>
<groupId>org.alfresco</groupId>
<artifactId>sample-module</artifactId>
<version>1.0-SNAPSHOT</version>
</parent>
<dependencies>
<!-- Add here any JAR or AMP dependency that needs to be deployed to ACS -->
<!-- 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.

100
docs/advanced-topics/debugging/debug-eclipse.md Normal file
View 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).
![Alt text](../../docassets/images/sdk-debug-eclipse-create.png?raw=true "Eclipse remote debug create configuration")
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`.
![Alt text](../../docassets/images/sdk-debug-eclipse-config.png?raw=true "Eclipse remote debug configuration detail")
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.
![Alt text](../../docassets/images/sdk-debug-eclipse-launch.png?raw=true "Eclipse remote debug configuration launch")
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.
![Alt text](../../docassets/images/sdk-hellofromjava.png?raw=true "Hello World webscript original result")
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:
![Alt text](../../docassets/images/sdk-debug-eclipse-breakpoint.png?raw=true "Eclipse remote debug stopped at 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
View 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).
![Alt text](../../docassets/images/sdk-debug-intellij-create.png?raw=true "IntelliJ remote debug create configuration")
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`.
![Alt text](../../docassets/images/sdk-debug-intellij-config.png?raw=true "IntelliJ remote debug configuration detail")
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.
![Alt text](../../docassets/images/sdk-debug-intellij-launch.png?raw=true "IntelliJ remote debug configuration launch")
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.
![Alt text](../../docassets/images/sdk-hellofromjava.png?raw=true "Hello World webscript original result")
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:
![Alt text](../../docassets/images/sdk-debug-intellij-breakpoint.png?raw=true "IntelliJ remote debug stopped at 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.

285
docs/advanced-topics/hot-reloading/hotswap-agent.md Normal file
View 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.
![Alt text](../../docassets/images/sdk-hellofromjava.png?raw=true "Hello World webscript original result")
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:
![alt text](../../docassets/images/sdk-hellofromme.png?raw=true "Hello World webscript modified result")
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
View 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`.
![Alt text](../../docassets/images/sdk-jrebel-eclipse-server.png?raw=true "Eclipse JRebel remote server configuration")
7. Select the checkbox to enable the server synchronisation and the checkbox to `Synchronize on build`.
![Alt text](../../docassets/images/sdk-jrebel-eclipse-servers.png?raw=true "Eclipse JRebel remote servers synchronization")
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).
![Alt text](../../docassets/images/sdk-jrebel-eclipse-projects.png?raw=true "Eclipse JRebel projects configuration")
## 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.
![Alt text](../../docassets/images/sdk-jrebel-intellij-server.png?raw=true "Eclipse JRebel remote server configuration")
7. Select the checkbox to enable the server synchronisation and the checkbox to `Synchronize on build`.
![Alt text](../../docassets/images/sdk-jrebel-intellij-servers.png?raw=true "Eclipse JRebel remote server configuration")
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).
![Alt text](../../docassets/images/sdk-jrebel-intellij-projects.png?raw=true "Eclipse JRebel projects configuration")
## 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.
![Alt text](../../docassets/images/sdk-hellofromjava.png?raw=true "Hello World webscript original result")
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:
![alt text](../../docassets/images/sdk-hellofromme.png?raw=true "Hello World webscript modified result")
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
View 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
View 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`.
![Alt text](../../docassets/images/sdk-it-eclipse-run.png?raw=true "Eclipse integration tests run")
Once the tests have completed (typically, after a few seconds), the results are presented.
![Alt text](../../docassets/images/sdk-it-eclipse-results.png?raw=true "Eclipse integration test execution results")
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`.
![Alt text](../../docassets/images/sdk-it-intellij-run.png?raw=true "IntelliJ IDEA integration tests run")
Once the tests have completed (typically, after a few seconds), the results are presented.
![Alt text](../../docassets/images/sdk-it-intellij-results.png?raw=true "IntelliJ IDEA integration test execution results")
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
View 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.

59
docs/advanced-topics/switching-versions.md Normal file
View File

@@ -0,0 +1,59 @@
---
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>
```
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.

74
docs/advanced-topics/working-with-enterprise/README.md Normal file
View File

@@ -0,0 +1,74 @@
---
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>
```
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`.

118
docs/advanced-topics/working-with-enterprise/alfresco-transform-service.md Normal file
View File

@@ -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.

20
docs/advanced-topics/working-with-enterprise/enterprise-docker-registry.md Normal file
View File

@@ -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/).

31
docs/advanced-topics/working-with-enterprise/enterprise-mvn-repo.md Normal file
View File

@@ -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.