Alfresco SDK 4.0

Document created by resplin Employee on Jun 6, 2015Last modified by alfresco-archivist on Aug 31, 2016
Version 2Show Document
  • View in full screen mode

{{Obsolete}}

NOTE - This page refers to an SDK which is now deprecated and might be dropped in the future. Please refer to the (Maven) Alfresco SDK to start developing on Alfresco. Full official supported user documentation and examples are available at Alfresco Docs, while for advanced configuration documentation for the SDK refer to the Maven Site Documentation. Up to date samples based on this SDK are available here

Back to Developer Guide

Previous version of SDK Alfresco SDK 3.4

Welcome to the Alfresco SDK for 4.0

Alfresco  provides a developer oriented download bundle, known as the Alfresco  SDK (Software Development Kit) to complement the Alfresco release  bundle.

This page outlines the steps required to start developing with the Alfresco SDK.


Purpose of the Alfresco SDK


The Alfresco SDK provides support for developers who wish to extend or customise the Alfresco platform.

It's been designed for the developer to get developing with minimal fuss for the following development scenarios:


  1. Developing Alfresco Repository plug-ins such as:
    • Custom Actions / Conditions
    • Custom Aspects
    • Custom Transformers
    • Creating an AMP
  2. Developing Applications against a standalone Alfresco server via Alfresco's Web Service API
  3. Embedding Alfresco into existing Applications via Alfresco's Java Foundation API or standards-compliant JCR API

The SDK also contains the Java Doc for the Alfresco API



Some  say typically, the SDK is used stand-alone, but how do you see the  results without using Alfresco Explorer or Alfresco Share?  An Alfresco Release  Installation is also required if performing any of the following:


  1. Customising the Alfresco Web Client
  2. Testing a custom Application that connects to a remote Alfresco Server
  3. Deploying a tested custom plug-in to a remote Alfresco Server



You  need to install both Alfresco, Tomcat and Eclipse on the same system.  Please note, SDK and Alfresco Version have to match in order to work  correctly.

The SDK is not designed for re-building  Alfresco, it does not provide full build scripts and artifacts,  therefore if you wish to develop bug fixes or extend the core  functionality of the Alfresco platform, you should use the full Alfresco  development environment provided in the Alfresco SVN Repository.


Downloading and Installing the SDK


1. Prerequisites: Ensure the following development tools are installed...


  • JDK 1.6.x
  • Eclipse IDE
  • MySql (well, actually a Database of choice, but MySQL or PostgresSQL recommended for development purposes)

2. Download the Alfresco Community Edition Release from the downloads page. Community_file_list_4.0.d

3.   Download the Alfresco SDK   The SDK bundle is provided in .zip  and .tar.gz formats.  A separate package is  available for each Alfresco release.

4. Unpack the downloaded package to a file system folder of your choice.

5. It's now installed.


SDK Contents


An expanded Alfresco SDK contains the following directories and top-level files:



/bin          - supporting dll's, exe's
/doc          - zipped Javadoc's for all pre-built libaries
/lib          - pre-built Alfresco .jars
  /deployment   - WCM deployment libraries
  /remote       - Alfresco libraries required for access to a remote Alfresco server
    /wsdl          - Web Services Definition Files
    /dependencies  - supporting libraries,
  /server       - Alfresco libraries required for embedding an Alfresco server
    /config    - alfresco sample configuration files.
    /dependencies - third party dependencies.
    Alfresco server libraries
  /share - Alfresco Share libraries.
/licenses     - third party license files
/src          - zipped source code for all pre-built libraries
/samples      - template Eclipse projects for common development scenarios

readme.txt    - Alfresco readme


Getting Started


This section explains how to setup your Eclipse environment for use with the Alfresco SDK.


Install 4.0 Community Edition Alfresco


Run the install file.

Test to make sure you can access alfresco (link is in Programs menu in Windows).


Set Eclipse Compiler Compliance Level to 6.0


Alfresco from 4.0 uses Java 1.6 language features, therefore Eclipse must be configured appropriately for JDK 1.6.


  1. Select Window -> Preferences... menu option
  2. Select Java -> Compiler preference in tree view
  3. Select 1.6 in Compiler compliance level
  4. Choose OK

Handle finding Win32NetBios or Win64NetBios


Add the alfresco bin folder to the system PATH. 

Alternatively you theoretically should be able to add it to the java.library.path variable.




Import the Alfresco Eclipse Projects


The  easiest and quickest way to explore the samples is via Eclipse.  Each  sample comes with its own Eclipse project which may be used as a  template for future developments of a similar kind.


  1. Start Eclipse
  2. Select File -> Import...
  3. Choose 'General -> Existing Projects into Workspace' import source and select Next
  4. Choose Select root directory option and select Browse...
  5. Navigate to the root file system folder where you unpacked the Alfresco SDK and select OK. Resist the temptation to navigate to samples, or you will not get SDK AlfrescoEmbedded and SDK AlfrescoRemote.
  6. The Alfresco Projects are now listed  under Projects as  follows...

    SDKProjectsInEclipse3.3.JPG
  7. Select Finish

At this point, all SDK projects are now imported.

Check Build hints window for error. Known fixes are listed below


Fix Classpath issues


From this tutorial : [http://charles.torda.net/2011/12/22/alfresco-4-0b-using-sdk-in-eclipse/]
A know issue for the 4.0.c SDK.
Open your project in your file browser.
Open the .classpath file (at the root of your project) and remove the white spaces (if any) before the <xml> tag.
Refresh your eclipse project, it should fix the build issues.


Modify Projects' alfresco-global.properties file to run against existing Alfresco CE installation


Each one of the examples has its own configuration file. The configuration file tells the example application critical information about your Alfresco repository such as which database to connect to and where the data directory resides. To run the examples against your existing CE (Community Edition) installation, for each example, do the following:


  • Change the alfresco-global.properties file to point to the location you installed content store for dir.root (ie  C:/Alfresco/alf_data)
  • Uncomment dbname, dbpassword and MySql driver and url configurations

If you already have a working installation on your machine, you can just overwrite the example application's local alfresco-global.properties file with the contents of your working alfresco-global.properties file.
You can find this file in : alfresco-4.0.d/tomcat/shared/classes


Explore the Sample Projects


There are two projects of particular importance:

SDK  AlfrescoEmbedded - this project provides references to the  libraries required for Alfresco Embedded use.

SDK AlfrescoRemote - this project provides references to the libraries required for Alfresco Remote use.

Each of the sample projects depends on one of the above.

SDK  FirstFoundationClient - use of embedded Alfresco server  via the Foundation API.

SDK  FirstJCRClient - use of embedded Alfresco server via the  JCR  API.

SDK FirstWebServiceClient -  use of remote Alfresco server via the   Web Services API.

SDK JCRSamples - a mixture of JCR code samples including a simple WIKI demonstration.

SDK WebServiceSamples - a mixture of Web Service samples.

SDK  CustomAction - how to develop a custom Action which may be  deployed to an Alfresco Repository.

SDK  CustomAspect - how to develop a custom Aspect with behaviour  which may be deployed to an Alfresco Repository.

SDK CustomJSP - how to develop and configure a custom JSP for the Alfresco Web Client.

SDK CustomDialog - how to develop and configure a custom Dialog for the Alfresco Web Client.

SDK CustomWizard - how to develop and configure a custom Wizard for the Alfresco Web Client.

SDK CustomLogin - example demonstrating how to override Login page of the Alfresco Web Client.

SDK  TaggingSample - example demonstrating how to adding document  tagging behaviour to the Alfresco Web Client.

SDK Basic AMP - example demonstrating how to build an AMP (Alfresco Module Package) file.


Associate source code and Javadocs with Alfresco Libraries (optional)


Whilst  developing against Alfresco it is useful to have access to Alfresco's  source code and Java documentation.  Within Eclipse, it's possible to  associate such material with the libraries you're using.

For example, to associate source code and Javadoc with the Alfresco repository.jar in Eclipse...


  • Expand the SDK AlfrescoEmbedded project
  • Expand the Referenced Libraries (Note: do not select jar files under dependencies)
  • Select alfresco-repository.jar (Note: the jar files may not be in alphabetical order) and right-click select Properties
  • Select Javadoc Location and Javadoc in archive option
  • Select Browse and navigate to folder /doc/api within your Alfresco SDK install folder
  • Select repository-doc.zip and select Open
  • Select Validate... and either select Ok or Cancel depending upon whether you want to view the Javadoc in a Web browser
  • Select Java Source Attachment
  • Select External File... and navigate to folder /src within your Alfresco SDK install folder
  • Select repository-src.zip and select Open
  • Select Ok

Repeat above for in SDK Alfresco embedded:


  • alfresco-core.jar
  • alfresco-remote-api.jar
  • alfresco-web-client.jar

SDK Alfresco Remote:


  • alfresco-web-service-client.jar, only sources are available

Running your first Alfresco Client


The  first sample to try is SDK FirstFoundationClient  which demonstrates the use of an embedded Alfresco Repository via the  the Java Foundation API.  It simply connects to the Repository and  creates a file in the 'Company Home' folder of the Web Client.

Before  turning the ignition key, the first step is to ensure an appropriate  database is setup for the Alfresco Repository, but this is only  necessary if you did not install the Community edition version in  addition to the SDK.

If you do not have a CE installed  with a database already and you are using MySQL, the following may be  issued from the shell script:

mysqladmin -u root -p create alfresco
mysql -u root -p -e 'grant all on alfresco.* to 'alfresco'@'localhost' identified by 'alfresco' with grant option;'
mysql -u root -p -e 'grant all on alfresco.* to 'alfresco'@'localhost.localdomain' identified by 'alfresco' with grant option;'

Alternatively you can run the batch/sql file:

/extras/databases/mysql/db_setup.bat (which calls db_setup.sql)

The SDK FirstFoundationClient project consists of the following source folders:

/alfresco/extension - runtime configuration files (e.g. database connection details)

/org/alfresco/sample - Sample application consisting of FirstFoundationClient.java

Check  the database connection details are correct  (alfresco-global.properties) and then it's simply a case of running or  debugging the FirstFoundationClient.java  application within Eclipse.

The sample will initialise  the Repository if it is the first client to connect to the Repository.   In this case, the sample will take longer to execute as all Repository  bootstrap data is installed into the database.

IMPORTANT  NOTE - Alfresco CE tomcat can not be running at the same time as the  samples.  Shutdown tomcat and run the example.  Then start Alfresco  Tomcat again from programs menu, log in and you should see the results  of the samples that ran.  For instance, after running the  FirstFoundationClient when you start Alfresco CE again and log in, under  the Company Home space you will see the content created by the example.


Developing a Custom Plug-in


The  projects SDK CustomAction and SDK  CustomAspect demonstrate how to develop a plug-in for the  Alfresco Repository.  Plug-ins can be developed and tested with an  embedded Alfresco Repository.  Then, once satisfied, a plug-in can be  packaged into a .jar which may then be deployed to any existing Alfresco  installation.  For example, the SDK CustomAspect  project has a JUnit sample that tests the custom aspect by running an  embedded Alfresco Repository using the Java Foundation API.

For  each applicable SDK project, a build.xml file has  been provided for packaging to a .jar file.  See Packaging And  Deploying Extensions for details on how to deploy extensions.


Executing the Web Services Examples


To  execute any of the Web Service Samples for Java it is necessary to  have an existing Alfresco Server installation to connect to.  The  easiest option is to install Alfresco.

The location of the Alfresco server to connect to is specified in the file webserviceclient.properties.

Note:  This file is located in /alfresco for the SDK  FirstWebServiceClient project and in  /alfresco/extension for the SDK WebServiceSamples  project.


Developing Custom Web Clients


The  custom web client samples include:  SDK CustomJSPSDK CustomDialogSDK  CustomWizard, SDK  CustomLogin and SDK  TaggingSample.

To deploy and test Web Client customisations it is necessary to have an existing Alfresco Server to deploy to.

Documentation  to support the SDK Web Client samples is available at Web Client  Configuration Guide and Web Client Customisation Guide.

The  SDK contains ANT build scripts, with the option to integrate your  extension into an existing Alfresco WAR file. For example, you can copy  your Alfresco WAR file to one of the sample directories (such as  samples/TaggingSample) and then run:

  ant integrate-extension

For more details, see Packaging_And_Deploying_Extensions#Integrated_deployment


Building an AMP File


Alfresco  extensions may be packaged into an AMP file for  subsequent deployment into any existing Alfresco installation.  The  project demonstrates how to structure a project to build an AMP file.

The  SDK Basic AMP project is a small SDK sample that  show how classes and configuration files can be arranged to generate an  Alfresco Module Package (AMP). For more details on the supported layout  of files, see: AMP file

Use ANT to generate the AMP file from the build script:

  ant -f build.xml

To  deploy your SDK Basic Sample AMP, you can download the  Module_Management_Tool into a working directory and then copy the  generated AMP file and Alfresco WAR file into the same working  directory.

The following example command will preview the change:

  java -jar alfresco-mmt-2.1.jar install alfresco-sdk-custom-service.amp alfresco.war -preview

The following example command will actual modify your working copy of the Alfresco WAR file: 

  java -jar alfresco-mmt-2.1.jar install alfresco-sdk-custom-service.amp alfresco.war -verbose

The  modified Alfresco WAR can then be re-deployed back into your Alfresco  server installation. If using Tomcat, you can shutdown Tomcat, delete  the webapps/alfresco sub-directory and place the modified Alfresco WAR  into webapps.

On re-starting the server, the Tomcat console will show that the custom class has been initialised during startup:

  SDK Demo AMP class has been loaded

and also the module component has been installed and started:

  13:13:51,712 INFO  [repo.module.ModuleServiceImpl] Found 1 module(s).
  13:13:52,509 INFO  [repo.module.ModuleServiceImpl] Installing module 'sdkDemoAmp' version 1.0.
  DemoComponent has been executed

Building the SDK from SVN


You can build the SDK from SVN source using ANT:

  ant -f continuous.xml distribute-sdk

Enterprise SDK is built as follows:

  ant -f continuous.xml -Dbuild.script=enterpriseprojects/build.xml distribute-sdk

Finally


Alfresco  documentation is continuously being improved.  If you see any issues  with this documentation please feel free to fix via our WIKI editing  capabilities.  Again, if you get stuck, don't forget the Developer Resources.
SDK
4.0
Overview
Getting Started

Attachments

Outcomes