Alfresco SDK on NetBeans

[resplin]

{{Obsolete}}

NOTE - This page refers to an SDK which is now deprecated and might be dropped in the future. The official developer documentation for Alfresco 5.0 is here: http://docs.alfresco.com/5.0/concepts/dev-for-developers.html

Welcome to the Alfresco SDK on NetBeans Guide

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 using NetBeans. Please refer the pages pointed to by hyperlinks for more information on the topics.

Some people claim that the SDK should not contain the source code (See comments in Alfresco forum http://forums.alfresco.com/en/viewtopic.php?f=10&t=12045)

Table of Contents

• 1 Purpose of the Alfresco SDK


• 2 Developer Resources


• 3 Downloading and Installing the SDK


• 4 Getting Started
  
  
  
  • 4.1 NetBeans Setup
  
  
  • 4.2 Import the Alfresco SDK Eclipse Projects into NetBeans
  
  
  • 4.3 Post-import steps for both types of developers
  
  
  • 4.4 Fix Issues Identified Already
  
  
  • 4.5 Explore the Sample Projects
  
  


• 5 Wrapping Up

Purpose of the Alfresco SDK

The Alfresco SDJK is available for Developers looking to customise the Alfresco platform. It's main Use Cases are as follows:

1. Developing Alfresco Repository plug-ins, for example::
   
   • Custom Actions / Conditions
     
   • Custom Aspects
     
   • Custom Transformers
     
2. Developing Applications using Alfresco's Web Service API, but without using the API directly.
   
3. Embedding Alfresco into other Applications using the Alfresco Java Foundation API or using a standards-compliant Java Content Repository API
   

More information about the purpose of the Alfresco can be found here

Developer Resources

Alfresco developer reference documentation is available in the Developer Guide section of the Alfresco WIKI.

For bug and issue reporting, use the Alfresco Bug and Issue Tracking Application.

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

For any other information start with the Alfresco Developer Website.

Downloading and Installing the SDK

For details on how to download and install the Alfresco SDK see the Downloading and Installing the SDK section of the Alfresco SDK page. A full list of the SDK contents is available in the SDK Contents section of the same page

Getting Started

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

NetBeans Setup

• The preferred versions of NetBeans for Alfresco are 6.0.1 and above. Though previous versions are not supported, a user shouldn't face any hassles following the same steps
  
• Firstly, add the alfresco bin folder to the system PATH before starting up NetBeans
  
• Set the NetBeans java compiler compliance level to JDK 5. This can be done by setting the value of “netbeans_jdkhome” property in [NETBEANS_HOME[/etc/netbeans.conf to the homedirectory of JDK 5. Alternatively, the default location of JDK can be overridden by using --jdkhome <dir> while starting NetBeans from the command line.
  
• Install the “Eclipse Project Importer” plugin from the NetBeans repository. The current version is 1.32.0.1.2.43. This adds the ability to import eclipse projects into NetBeans. Note that from NetBeans version 6.1 onwards this plugin will be available by default. More details can be found here
  

Import the Alfresco SDK Eclipse Projects into NetBeans

There are 2 possible scenarios:

An Alfresco developer on eclipse who is looking to migrate to NetBeans:

• Go to File -> Import Projects -> Eclipse Projects
  
• Select the option “Import projects from Workspace” and select the eclipse workspace directory which contains the Alfresco SDK projects
  
• In the next window, select all the SDK projects, enter the “location of NetBeans projects” and click “finish”
  
• Note that NetBeans creates only a reference to the actual sources in Eclipse workspace. This means you can now work in Eclipse and NetBeans at the same time and keep the files at same place.
  

A developer new to Alfresco who is looking to build Alfresco using NetBeans:
● This requires an additional step to the process described above. You need to create a pseudo eclipse workspace to make use of the “eclipse project importer plugin” in NetBeans by creating the following directory structure: (A zip file containing the below mentioned resources is available here. Unzip it in the correct location)

[SDK_ROOT]
     |
     samples
            |
            .metadata
                    |
                    .plugins
                           |
                           org.eclipse.core.resources
                                                    |
                                                    .projects
                           org.eclipse.core.runtime
                                                  |
                                                  .settings

• Under the directory [SDK_ROOT]/samples/.metadata/.plugins/org.eclipse.core.runtime/.settings create 2 files with the following contents:
  

File name : org.eclipse.jdt.launching.prefs

Content :
org.eclipse.jdt.launching.PREF_VM_XML=<vmSettings defaultVM\=''>\r\n<vmType id\=''>\r\n<vm id\='' name\='java' path\=''/>\r\n</vmType>\r\n</vmSettings>\r\n

File name : org.eclipse.jdt.core.prefs

Content : Empty file

NOTE: The value of org.eclipse.jdt.launching.PREF_VM_XML should be a on single line, check this if you cut and paste from the above text as some systems might insert additional line feeds

• If you are on a UNIX based OS, create the following softlinks:
  
  • ln -s [SDK_ROOT]/lib/server SDK_ROOT/samples/server
    
  • ln -s [SDK_ROOT]/lib/remote SDK_ROOT/samples/remote
    
• If you are on Windows, copy the directories [SDK_ROOT]\lib\server> and [SDK_ROOT]\lib\remote to [SDK_ROOT]\samples
  
• After creating the required files and directories, go to File -> Import Projects -> Eclipse Projects. Select the option “Import projects from Workspace” and select the [SDK_ROOT]/samples directory which contains the Alfresco SDK projects. In the next window, select all of the SDK projects, enter the “location of NetBeans projects” and click “finish”
  

sdk-screen1.jpg

Post-import steps for both types of developers

While importing the SDK projects into NetBeans, the classpath libraries of “SDK AlfrescoEmbedded” and “SDK AlfrescoRemote” are not exported to the dependent projects. To solve this problem you have to create 2 libraries manually and link them to the projects. Here is how you do it:


1. Create a library called “AlfrescoEmbedded”(Tools->Libraries->New Library) of type “Class libraries”

2. Unjar the contents of [SDK_ROOT]/lib/server/config.jar. Add the config directory to “AlfrescoEmbedded” library through the 'Add Jar/Folder..' button

3. Now, select all the jars found in [SDK_ROOT]/samples/server directory. Remember to exhaustively select all the jars by recursively traversing each of the sub-directories

sdk-screen2.jpg

4. Create a library called “AlfrescoRemote”(Tools->Libraries->New Library) of type “Class libraries”

5. Select all the jars found in SDK_ROOT/samples/remote directory. Remember to exhaustively select all the jars by recursively traversing each of the sub-directories

sdk-screen3.jpg

6. You can optionally associate source and javadoc for the both the libraries as it is useful to have access to Alfresco's source code and Java documentation while developing. First, unzip *-src.zip files in the [SDK_ROOT]/src directory. Now, click on the 'Sources' tab in the library manager window and using the 'Add jar/folder' button, select the java directory under each of the unzipped src directories. Similarly add javadocs through the 'javadocs' tab. Using the “Add Zip/folder” button, select *-doc.zip files in [SDK_ROOT]/doc/api

7. Now add the libraries to each of the SDK projects that depend on them (Project Properties->Libraries->Add Library). Add 'AlfrescoEmbedded' library to a project if ”SDK AlfrescoEmbedded – dist/SDK_AlfrescoEmdedded.jar” is its compile-time library. Similarly, add 'AlfrescoRemote' library to a project if ”SDK AlfrescoRemote – dist/SDK_AlfrescoRemote.jar” is its compile-time library. Typically, the webservice projects will need AlfrescoRemote library and the rest will need the AlfrescoEmbedded library

Fix Issues Identified Already

Find any fixes necessary to get the SDK to work:
http://issues.alfresco.com/secure/IssueNavigator.jspa?reset=true&mode=hide&pid=10011&component=10102

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
  

Wrapping Up

The Existing Alfresco SDK Wiki page has a number of additional steps that it's easier to link to. Here's a step by step list of links for your reference:

• Running your first Alfresco Client
  
• Developing a Custom Plug-in
  
• Executing the Web Services Examples
  
• Developing Custom Web Clients
  
• Building an AMP file
  
• Building the SDK from SVN