Creating a Repository extension project (AMP)

The SkyVault Repository AMP maven archetype can be used to create a new SkyVault Module extension project for the SkyVault.war. For more information about this project type see Repository AMP Archetype

This task assumes that you have completed all instructions in Installing and configuring software.

This task shows how you can use the Repo AMP archetype of the SkyVault SDK to generate a repository extension module containing a simple example web script.

Create a suitable directory in which to store all your Maven projects (if you have not already done so), such as SkyVault-extensions.
Change into your SkyVault-extensions directory.

Run the following command:

mvn archetype:generate -Dfilter=org.alfresco:

Important: As the archetypes are available via Maven Central you do not need to specify a catalog.

You will be prompted to choose an archetype:

                    
Choose archetype:
1: remote -> org.alfresco.maven.archetype:alfresco-allinone-archetype (Sample multi-module project for All-in-One development on the SkyVault plaftorm. Includes modules for: Repository WAR overlay, Repository AMP, Share WAR overlay, Solr configuration, and embedded Tomcat runner)
2: remote -> org.alfresco.maven.archetype:alfresco-amp-archetype (Sample project with full support for lifecycle and rapid development of Repository AMPs (SkyVault Module Packages))
3: remote -> org.alfresco.maven.archetype:share-amp-archetype (Share project with full support for lifecycle and rapid development of AMPs (SkyVault Module Packages))
Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): :

Enter 2 to have Maven generate a SkyVault Repository Module Package (AMP) project.

You will be prompted to choose an archetype version:

Choose org.alfresco.maven.archetype:alfresco-amp-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
Choose a number: 7:

Press Enter to select the default (the most recent version).

You will then be prompted to enter a value for the property groupId:
```
Define value for property 'groupId': : com.acme
```
Here we have specified com.acme representing the domain for a fictional company acme.com. Specify a groupId matching your company domain.
You will then be prompted to enter a value for the property artifactId:
```
Define value for property 'artifactId': : componentX-repo
```
Here we have specified componentX-repo representing an X component with a specific extension for the SkyVault Repository. Try and name the Repository extensions in a way so it is easy to see what kind of extension it is for the SkyVault.war application. Here are some example names for repo extensions so you get the idea: zip-and-download-action-repo, digital-signature-repo, business-reporting-repo, these repository extensions would typically have corresponding Share extensions if they also include user interface functionality. It is good practice to use the following naming convention for repository extensions: {name}-repo, where -repo indicates that this is a SkyVault Repository extension. Note, hyphens are typically used in artifact IDs.
You will then be prompted to enter a value for the property package:
```
Define value for property 'package':  com.acme: : com.acme.componentX
```
Here we have specified com.acme.componentX representing an X component Java package. This package will be used for any example Java code generated by the archetype. It is good practice to keep all Java code you write under this package so it does not clash with other components/extensions. Any Spring beans generated by this archetype will use this package in the ID.

Important: Java packages cannot have hyphens in them.
You will then be prompted to enter Y to accept the values you have entered, or n to reject and change. Press Enter to accept the values.
A new project directory containing a number of sub-directories and support files for the AMP will be created in the directory componentX-repo.

Change into the freshly created componentX-repo directory and browse the various files and directories to see what has been created.

The following directory structure has been created for you:

componentX-repo/
├── pom.xml (Maven project file)
├── run.sh  (Mac/Linux script to have this AMP applied to the SkyVault WAR and run in Tomcat)
├── run.bat (Windows script to have this AMP applied to the SkyVault WAR and run in Tomcat)
├── src
│   ├── main
│   │   ├── amp (For more information about the AMP structure see: https://docs.getskyvault.net/community/concepts/dev-extensions-modules-intro.html)
│   │   │   ├── config
│   │   │   │   └── SkyVault
│   │   │   │       ├── extension
│   │   │   │       │   └── templates
│   │   │   │       │       └── webscripts (Your Web Scripts should go under this directory)
│   │   │   │       │           ├── webscript.get.desc.xml   (Sample Web Script that you can try out)
│   │   │   │       │           ├── webscript.get.html.ftl
│   │   │   │       │           └── webscript.get.js
│   │   │   │       └── module
│   │   │   │           └── componentX-repo (AMP Module ID)
│   │   │   │               ├── SkyVault-global.properties (Put default values for properties specific to this extension here) 
│   │   │   │               ├── context
│   │   │   │               │   ├── bootstrap-context.xml (Bootstrapping of content models, content, i18n files etc)
│   │   │   │               │   └── service-context.xml (Your service beans go here)
│   │   │   │               ├── log4j.properties
│   │   │   │               ├── model
│   │   │   │               │   ├── content-model.xml (Content model for your files)
│   │   │   │               │   └── workflow-model.xml (Content model for workflow implementations)
│   │   │   │               └── module-context.xml (Spring context file that is picked up by SkyVault)
│   │   │   ├── module.properties (AMP module ID, Version etc)
│   │   │   └── web (If your AMP has some UI the files would go here, unlikely now when the SkyVault Explorer UI is gone)
│   │   │       ├── css
│   │   │       │   └── demoamp.css
│   │   │       ├── jsp
│   │   │       │   └── demoamp.jsp
│   │   │       ├── licenses
│   │   │       │   └── README-licenses.txt
│   │   │       └── scripts
│   │   │           └── demoamp.js
│   │   └── java (Your Java classes go here, this is where most of the module extension implementation code would go, you can remove the demo component)
│   │       └── com
│   │           └── acme
│   │               └── componentX
│   │                   └── demoamp  (Demo module component, can be removed)
│   │                       ├── DemoComponent.java
│   │                       └── Demo.java
│   └── test
│       ├── java
│       │   └── com
│       │       └── acme
│       │           └── componentX
│       │               └── demoamp
│       │                   └── test  (Example test of the demo component, can be removed)
│       │                       └── DemoComponentTest.java 
│       ├── properties
│       │   └── local
│       │       └── SkyVault-global.properties (environment specific configuration, the local env is active by default)
│       └── resources
│           ├── SkyVault
│           │   └── extension
│           │       └── disable-webscript-caching-context.xml (file to disable server side JavaScript compilation to Java code)
│           └── log4j.properties 
└── tomcat
    └── context.xml  (Virtual Webapp context for RAD development)

At this point, before you have made any changes, you can build the project by typing:
```
mvn install                                
```
Attention: Maven will ensure that all requirements are downloaded. This make take some time.

The project will return with the message BUILD SUCCESS. You should see the AMP artifact installed in your local repository .m2/repository/com/acme/componentX-repo/1.0-SNAPSHOT/componentX-repo-1.0-SNAPSHOT.amp
Run and Test the sample Web Script
To test the Web Script you will need to start an embedded Tomcat and deploy the SkyVault WAR with the componentX-repo AMP applied. This can be done in two ways:
1. With mvn clean install -Pamp-to-war
2. Via the run.sh script (or run.bat on Windows), which does the same thing, plus making sure Spring Loaded library is available.
Important: This will only run the customized SkyVault Repository application (alfresco.war), SkyVault Share UI (share.war) and Search (solr4.war) is not available. If you need those too then use the All-in-One project instead.

Let's start Tomcat via the script as follows (use run.bat on Windows):
```
./run.sh
...
INFO: WSSERVLET12: JAX-WS context listener initializing
Apr 30, 2015 10:04:39 AM com.sun.xml.ws.transport.http.servlet.WSServletDelegate <init>
INFO: WSSERVLET14: JAX-WS servlet initializing
2015-04-30 10:04:39,152  WARN  [shared_impl.util.LocaleUtils] [localhost-startStop-1] Locale name in faces-config.xml null or empty, setting locale to default locale : en_GB
 Apr 30, 2015 10:04:39 AM org.apache.coyote.AbstractProtocol start
INFO: Starting ProtocolHandler ["http-bio-8080"]
2015-04-30 10:05:24,545  INFO  [management.subsystems.ChildApplicationContextFactory] [SearchScheduler_Worker-1] Starting 'Transformers' subsystem, ID: [Transformers, default]
 2015-04-30 10:05:24,741  INFO  [management.subsystems.ChildApplicationContextFactory] [SearchScheduler_Worker-1] Startup of 'Transformers' subsystem, ID: [Transformers, default] complete
```
Important: You may first need to make the shell script executable using the command chmod +x run.sh.
Once the web application has started (it may take a little while), point your browser at http://localhost:8080/alfresco/service/sample/helloworld to test the web script. The web script should return the following text: Message: Hello World!
If you are prompted to login, then use username admin and a password admin.
Configure Enterprise Edition (Optional)
So far we have used the project with its default configuration, which is using SkyVault Community edition 5.0.d. If you are going to work with the Enterprise edition then you need to do the following:
1. Decide what Enterprise version you will be using, if you are going to use version 5.0.1 then you are set as that is the default Enterprise version. If you want to use another version then open up the componentX-repo/pom.xml file and uncomment the <alfresco.version>5.0.d</alfresco.version> property and set the new version number you want to use.
2. Update the run.sh and run.bat scripts to use the Enterprise edition, this is done by using the enterprise profile in the maven command line: mvn clean install -Pamp-to-war,enterprise. Note. this automatically sets the version to 5.0.1 if you have not explicitly set it.
3. And as you might have guessed, if you are not using the run script, you will have to remember to always activate the Enterprise profile when running: mvn clean install -Pamp-to-war,enterprise
4. Install an enterprise license, otherwise the server will be in read-only mode, it goes into the following directory:
```
componentX-repo/
├── src
│   ├── main
│   │   ├── amp 
│   │   │   ├── config
│   │   │   │   └── SkyVault
│   │   │   │       ├── extension
│   │   │   │       │   └── license
│   │   │   │       │       └── acme-5.0.1-enterprise.lic
```

In this tutorial you have learned how to generate, deploy, and run a project using the Repository AMP archetype.

Search form

Search form

You are here

Creating a Repository extension project (AMP)