Alfresco SDK 3.2

[resplin]

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

Back to Developer Guide

Next version of SDK Alfresco SDK 3.3

Issues :

• FirstFoundation cannot start ImageMagick, pdf2swf and soffice with relative path in Community Edition config
  

Welcome to the Alfresco SDK 3.2

From v1.3 onwards, 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.

Table of Contents

• 1 Purpose of the Alfresco SDK


• 2 Developer Resources


• 3 Downloading and Installing the SDK


• 4 SDK Contents


• 5 Getting Started
  
  
  
  • 5.1 Install 3.2 Community Edition Alfresco
  
  
  • 5.2 Set Eclipse Compiler Compliance Level to 6.0
  
  
  • 5.3 Handle finding Win32NetBios
  
  
  • 5.4 Import the Alfresco Eclipse Projects
  
  
  • 5.5 Modify Projects to run against Alfresco CE installation
  
  
  • 5.6 Reference libraries in SDK AlfrescoEmbedded project
  
  
  • 5.7 Fix Issues Identified Already
  
  
  • 5.8 Explore the Sample Projects
  
  
  • 5.9 Associate source code and Javadocs with Alfresco Libraries (optional)
  
  


• 6 Running your first Alfresco Client


• 7 Developing a Custom Plug-in


• 8 Executing the Web Services Examples


• 9 Developing Custom Web Clients


• 10 Building an AMP File


• 11 Building the SDK from SVN


• 12 Finally

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

Some say typically, the SDK is used stand-alone, but how do you see the results without using the Alfresco web client?  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 i.e. 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.

Developer Resources

For Alfresco developer reference documentation visit the Developer Guide section of the Alfresco WIKI.

To check for and report bugs and issues, use the Alfresco Bug and Issue Tracking Application.

To discuss any aspect of Alfresco with the community, use the Alfresco Forums.

Otherwise, visit the Alfresco Developer Website.

Downloading and Installing the SDK

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

• JDK 1.6.x or JDK 1.5.x
  
• Eclipse IDE 3.2+ (highly recommended)
  
• MySql 1.5.0.67 (well, actually a Database of choice, but MySQL is recommended for development purposes)
  

2. Download the Alfresco Community Edition Release from SourceForge.

3.  Download the Alfresco SDK from SourceForge.  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
/extras       - additional files - e.g. for MySQL db setup/removal
/lib          - pre-built Alfresco .jars
  /remote       - Alfresco libraries required for access to a remote Alfresco server
  /server       - Alfresco libraries required for embedding an Alfresco server
/licenses     - license files
/src          - zipped source code for all pre-built libraries
/samples      - template Eclipse projects for common development scenarios

licence.txt   - Alfresco licence file
notice.txt    - notices
readme.txt    - Alfresco readme

Getting Started

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

Install 3.2 Community Edition Alfresco

http://wiki.alfresco.com/w/images/6/62/Installing_and_Configuring_Alfresco_ECM_Community_Edition_3_2...

Set Eclipse Compiler Compliance Level to 6.0

Alfresco 3.2 can use either JDK 1.5 or 1.6, however 1.5 is now past it's end of life. (It works fine under 1.5, but installation sheets demand 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

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...
   
   SDKProjectsInEclipse.jpg
   
7. Select Finish
   

At this point, all SDK projects are now imported.

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

Modify Projects to run against Alfresco CE installation

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
  
• repeat above for all projects.
  

Reference libraries in SDK AlfrescoEmbedded project

In order to be able to run the SDK FirstFundationClient that references the SDK AlfrescoEmbedded project, it is necessary to reference in SDK AlfrescoEmbedded project all the libs in the 'dependencies' folder. Otherwise, when trying to run FirstFundationClient, you will get the error

Exception in thread 'main' org.springframework.beans.factory.CannotLoadBeanClassException: Cannot find class [org.alfresco.module.blogIntegration.BlogIntegrationServiceImpl] for bean with name 'blogIntegrationService' defined in class path resource [alfresco/blog-context.xml]; nested exception is java.lang.ClassNotFoundException: org.alfresco.module.blogIntegration.BlogIntegrationServiceImpl
Caused by: java.lang.ClassNotFoundException: org.alfresco.module.blogIntegration.BlogIntegrationServiceImpl

1. Right click the SDK AlfrescoEmbedded project
   
2. Choose Properties
   
3. Select Java Build Path link
   
4. Select the Libraries tab
   
5. Click Add JARs
   
6. Add all the jars present in the dependencies folder
   
7. Click OK twice
   

• 3.0 edition is missing the jlan jar and no one seems to have the correct version available anywhere.  Use 2.9 version of SDK for less trouble.
  
• 3.2 edition: Seems to be ok
  

Norgan 19:39, 20 July 2009 (BST)

Fix Issues Identified Already

Version 3.2 :

• Problem: version from 090705 was compiled with broken antscript, using absolute paths. Message: Project 'SDK AlfrescoEmbedded' is missing required library: 'G:\bamboo-home\xml-data\build-dir\ALF-COMMUNITY\root\build\assemble\sdk\lib\server\alfresco-core-3.2.jar'
  
• Fix: use files from forum ( Manual fix) or check out the ant files (i guess, see Jira). If you use the files from the forum, don't forget to remove and re-import the projects.
  

Norgan 18:29, 20 July 2009 (BST)

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 (in 3.2. source only
  
• alfresco-web-client.jar
  
• alfresco-webscript-framework.jar
  

SDK Alfresco Remote:

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

Not referenced in examples, but available in SDK directories:

• alfresco-web-framework.jar
  
• alfresco-share.jar
  

Norgan 19:39, 20 July 2009 (BST)

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 CustomJSP, SDK CustomDialog, SDK 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

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
Overview
3.2
Getting Started