JarCastingAlfred API
Documentation
Full
https://docs.xenit.eu/alfred-api/stable-user/index.html
Quickstart
Rules for pull requests
- Common sense trumps all rules.
- For every pull request please extend the CHANGELOG.md.
- Do not make breaking changes since this is an API used by customers. Breaking changes include adding, changing or removing endpoints or JSON objects used in requests and responses.
- If you are forced to make a breaking change:
- Notify maintainers
- Add a note to the changelog with upgrade instructions
- Notify all customers at the next release
- If you are forced to make a breaking change:
- When working in REST code, please comply to REST HTTP result codes policy outlined in the user guide.
- Prefer unit tests over integration tests to keep builds fast
- Avoid
this.prefix for consistency (unless the scope is ambiguous). - Follow our coding styleguide and other active procedures.
Project structure
- apix-interface builds the interface of Alfred API. This part is agnostic of the Alfresco version used.
- apix-rest-v1 builds the REST API of Alfred API.
- apix-impl builds the AMP which is the main deliverable for Alfred API. The AMP contains the JARs of apix-interface and apix-rest-v1.
- The top directory also contains code shared over different Alfresco versions.
- apix-impl/xx contains all code per Alfresco version. It has a src/java folder for code specific to that Alfresco version and a src/java-shared code for the code shared between versions. This code is automatically symlinked from the apix-impl directory.
- apix-integrationtests contains the integration tests for each Alfresco version.
How to
Run
The following command starts up all docker containers required for an Alfresco running Alfred API.
./gradlew :apix-docker:docker-${VERSION}:composeUp --info
Where VERSION is e.g. 51.
Run integration tests
./gradlew :apix-integrationtests:test-${VERSION}:integrationTest
Again, where VERSION is e.g. 51.
However, this starts (and afterwards stops) docker containers. This includes starting an Alfresco container, adding a startup time of several minutes. To circumvent this you also run the test on already running containers with for example:
./gradlew -x composeUp -x composeDown :apix-integrationtests:test-61:integrationTest -Pprotocol=http -Phost=localhost -Pport=8061
Run integration tests under debugger
- Debugging settings are already added by
apix-docker/${VERSION}/debug-extension.docker-compose.yml, including a portmapping8000:8000. This file does not get loaded when running in Jenkins. - Prepare your remote debugger in IntelliJ and set breakpoints where you want in your tests (or Alfred API code).
- Run the integration tests (see section above).
- Wait until the container is started and healthy, then attach the debugger.
Again, where VERSION is e.g. 51.
Deploy code changes for development
In a development scenario, it is possible to upload code changes to a running alfresco through dynamic extensions. This requires the running alfresco to already have an older or equal version of alfred-api installed, and the use of the jar artifact instead of the amp to do the new install. The JAR has the format apix-impl-{ALFRESCO-VERSION}-{APIX-VERSION}.jar and can be found under apix-impl/{ALFRESCO-VERSION}/build/libs/, where ALFRESCO-VERSION is one of (50|51|52|60|61|62). The new installation can be done either through the DE web interface, or with the following gradle task.
./gradlew :apix-impl:apix-impl-{ALFRESCO-VERSION}:installBundle -Phost={ALFRESCO-HOST} -Pport={ALFRESCO-PORT}
Where VERSION is e.g. 51 and here PORT is the port mapping of the alfresco-core container e.g. 32774.
Protip: If you get tired of changing the port after every docker-compose up, you can temporarily put a fixed port in the docker-compose.yml of the version you are working with. (The rationale behind using variable ephemeral ports is that during parallel builds on Jenkins port clashes must be avoided.)
For example for version 5.1, change in apix-docker/51/docker-compose.yml the ports line from:
services:
alfresco-core:
ports:
- ${DOCKER_IP}:8080
to:
services:
alfresco-core:
ports:
- ${DOCKER_IP}:9051:8080
and then restart the containers with:
./gradlew :apix-docker:docker-51:composeUp --info
REST HTTP result codes
Installation
Pre-requisites
Alfred API requires Dynamic Extensions For Alfresco, version 2.0.1 or later. This module should be installed first. Acquisition and installation instructions can be found here.
