Obtaining the SDK

If you are running the Enterprise network, it is likely that the SDK has been provided to you as a binary. Alternatively, you can check out the Enterprise source code and build it yourself. In the Enterprise SVN repository, specific releases are tagged. So if you wanted 2.2.0, for example, you’d check out V2.2.0-ENTERPRISE-FINAL. The Enterprise SVN repository for the Enterprise network is password-protected. Consult your Alfresco representative for the URL, port, and credentials that are needed to obtain the Enterprise source code.

Labs network users can either download the SDK as a binary from SourceForge (https://sourceforge.net/project/showfiles.php?group_id=143373&package_id=189441) or check out the Labs source code and build it. The SVN URL for the Labs source code is svn://svn.alfresco.com. In the Labs repository, nothing is tagged. You must check out HEAD.

Step-by-Step: Building Alfresco from Source

Regardless of whether you are using Enterprise or Labs, if you’ve decided to build from the source it is very easy to do it. At a high level, you simply check out the source and then run Ant. If you’ve opted to use the pre-compiled binaries, skip to the next section. Otherwise, let’s use Ant to create the same ZIP/TAR file that is available on the download page. To do that, follow these steps:

1. Check out the source from the appropriate SVN repository, as mentioned earlier.
2. Set the TOMCAT_HOME environment variable to the root of your Apache Tomcat install directory.
3. Navigate to the root of the source directory, then run the default Ant target: ant build.xml

   ant build.xml
   

4. It will take a few minutes to build everything. When it is done, run the distribute task like this:

   ant -f continuous.xml distribute
   

5. Again, it may take several minutes for this to run. When it is done, you should see several archives in the build|dist directory. For example, running this Ant task for Alfresco 3.0 Labs produces several archives. The subset relevant to the article includes:
   • alfresco-labs-sdk-*.tar.gz
   • alfresco-labs-sdk-*.zip
   • alfresco-labs-tomcat-*.tar.gz
   • alfresco-labs-tomcat-*.zip
   • alfresco-labs-war-*.tar.gz
   • alfresco-labs-war-*.zip
   • alfresco-labs-wcm-*.tar.gz
   • alfresco-labs-wcm-*.zip
6. You should extract the SDK archive somewhere handy. The next step will be to import the SDK into Eclipse.

Setting up the SDK in Eclipse

Nothing about Alfresco requires you to use Eclipse or any other IDE. But Eclipse is very widely used and the Alfresco SDK distribution includes Eclipse projects that can easily be imported into Eclipse, so that’s what these instructions will cover.

In addition to the Alfresco JARs, dependent JARs, Javadocs, and source code, the SDK bundle has several Eclipse projects. Most of the Eclipse projects are sample projects showing how to write code for a particular area of Alfresco. Two are special, however. The SDK AlfrescoEmbedded project and the SDK AlfrescoRemote project reference all of the JARs needed for the Java API and the Web Services API respectively. The easiest way to make sure your own Eclipse project has everything it needs to compile is to import the projects bundled with the SDK into your Eclipse workspace, and then add the appropriate SDK projects to your project’s build path.

Step-by-Step: Importing the SDK into Eclipse

Every developer has his or her own favorite way of configuring tools. If you are going to work with multiple versions of Alfresco, you should use version-specific Eclipse workspaces. For example, you might want to have a workspace-alfresco-2.2 workspace as well as a workspace-alfresco-3.0 workspace, each with the corresponding Alfresco SDK projects imported. Then, if you need to test customizations against a different version of the Alfresco SDK, all you have to do is switch your workspace, import your customization project if it isn’t in the workspace already, and build it. Let’s go ahead and set this up. Follow these steps:

1. In Eclipse, select File|Switch Workspace or specify a new workspace location. This will be your workspace for a specific version of the Alfresco SDK so use a name such as workspace-alfresco-3.0. Eclipse will restart with an empty workspace.
2. Make sure the Java compiler compliance level preference is set to 5.0 (Window|Preferences|Java|Compiler). If you forget to do that, Eclipse won’t be able to build the projects after they are imported.
3. Select File|Import|Existing Projects into Workspace. For the root directory, specify the directory where the SDK was uncompressed.

For the root directory, specify the directory where the SDK was uncompressed. You want the root SDK directory, not the Samples directory.

4. Select all of the projects that are listed and click Import.

After the import, Eclipse should be able to build all projects cleanly. If not, double-check the compiler compliance level. If that is set but there are still errors, make sure you imported all SDK projects including SDK AlfrescoEmbedded and SDK AlfrescoRemote.

Now that the files are in the workspace, take a look at the Embedded project. That’s quite a list of dependent JAR files! The Alfresco-specific JARs all start with alfresco-. It depends on what you are doing, of course, but the JAR that is referenced most often is likely to be alfresco-repository.jar because that’s where the bulk of the API resides.

The SDK comes with zipped source code and Javadocs, which are both useful references (although the Javadocs are pretty sparse). It’s a good idea to tell Eclipse where those files are, so you can drill in to the Alfresco source when debugging. To do that, right-click on the Alfresco JAR, and then select Properties. You’ll see panels for Java Source Attachment and Javadoc Location that you can use to associate the JAR with the appropriate source and Javadoc archives.

The following image shows the Java Source Attachment for alfresco-repository.jar:

The following image shows the Javadoc Location panel for alfresco-repository.jar.

Source and Javadoc are provided for each of the Alfresco JARs, as shown in the following table. Note that source and Javadoc for everything is available. This is open source software after all, not just all bundled with the SDK: