Alfresco One Developer Guide

Alfresco 5.1

Developer Guide

Contents Developer Guide........................................................................................................................ 3 Architecture.......................................................................................................................... 3 Access protocols..........................................................................................................6 Repository concepts.................................................................................................... 7 Mini Glossary............................................................................................................. 12 Alfresco SDK 2.2.0............................................................................................................ 16 What's new?.............................................................................................................. 16 Introduction to the Alfresco SDK............................................................................... 18 Getting Started with the Alfresco SDK...................................................................... 23 Maven Archetypes - Command Reference............................................................... 44 Rapid Application Development (RAD)..................................................................... 52 Advanced Topics....................................................................................................... 86 Upgrading.................................................................................................................122 Using the REST API Explorer................................................................................. 153 Using MySQL...........................................................................................................156

2 Alfresco 5.1

Developer Guide

Developer Guide The Developer Guide includes extensive guidance and reference materials to aid the developer in creating applications and extensions for Alfresco. This Developer Guide PDF does not include the full developer documentation and API references. To access the complete set of documentation, see the online Alfresco documentation. There are a number of approaches to developing for Alfresco depending on what you want to do. For example, if you are writing a client application, perhaps in Ruby or Python to connect to Alfresco either on-premise, or Alfresco in the Cloud, then you would most likely use the Alfresco REST API. If on the other hand you wanted to write a server-side extension in Java, you would use the Public Java API, or perhaps write a web script using Java, JavaScript and FreeMarker. Generally if you are creating extensions to Alfresco you would use the Alfresco SDK. This allows you to work in your IDE of choice, using technologies you already know, such as Java and Maven. This Developer guide attempts to lay out the various options available to you, so you can use the right approach, depending on what you want to achieve. Related Links Architecture on page 3 Alfresco SDK 2.2.0 on page 16

Architecture This gives a view of the architecture of Alfresco from the developer's perspective. Alfresco at its core is a repository that provides a store for content, and a wide range of services that can be used by content applications to manipulate the content. The following diagram illustrates the idea that Alfresco One can be thought of as consisting of three main components, Platform, User Interface (UI), and Search. These components are implemented as separate web applications:

Developer Guide 3

Developer Guide

The main component with all the core Enterprise Content Management functionality is called the Platform and is implemented in the alfresco.war web application. It provides the repository where content is stored plus all the associated content services. Alfresco Share provides a web client interface (that is a User Interface, UI) for the repository and is implemented as the share.war web application. Share makes it easy for users to manage their sites, documents, users and so on. The search functionality is implemented on top of Apache Solr 4 and provides the indexing of all content, which enables powerful search functionality. Besides the web clients accessing the Repository via Share there are also mobile clients that will access the content via REST APIs provided by the platform. If we dive deeper into the platform (packaged in alfresco.war) we will see that it also supports workflow in the form of the embedded Activiti Workflow Engine. The platform is usually also integrated with a Directory Server (LDAP) to be able to sync users and groups with Alfresco. And most installations also integrates with an SMTP server so the Alfresco Platform can send emails, such as site invitations. For more information about the internals of the Alfresco Platform, and specifically the content Repository, see the concepts section. Besides Share there are also many other clients that can connect to the Alfresco repository, including any CMIS-compatible client, and via the Microsoft SharePoint protocol any SharePoint client. Alfresco Cloud Sync can synchronize content between an on-premise installation of Alfresco and Alfresco in the Cloud, under user control. The Alfresco Platform also contains numerous APIs, Services, and Protocols.

4 Alfresco 5.1

Developer Guide

The following diagram illustrates this extended platform architecture:

Note that content metadata is stored in a relational database system such as PostgreSQL, MySQL, Oracle, and so on. The content itself is stored on the file system (or other storage system such as Amazon S3). Alfresco provides a number of extension points to allow you to customize it. These extensions points have various formats, but include: • Platform extension points and detailed architecture • Share extension points and detailed architecture • Share integration points and detailed architecture • APIs • Protocols • Services The links in the list above provide further information on each of these topics. Related Links Developer Guide on page 3 Access protocols on page 6 Repository concepts on page 7 Mini Glossary on page 12

Developer Guide 5

Developer Guide

Access protocols Alfresco supports a number of different protocols for accessing the content repository. Their availability extends the options available to developers, when building their own applications and extensions. Protocols provide developers with another possible avenue for building their own applications and extensions. For example, if you are building a client application to connect with multiple repositories from multiple vendors, including Alfresco, then CMIS is a consideration. If you are building a client to connect via the SharePoint Protocol, then use the Alfresco Office Services (AOS). Protocols provide a resource for developers, in addition to the numerous other extension points and APIs built into Alfresco. When any of these protocols are used to access or upload content to the Alfresco repository, access control is always enforced based on configured permissions, regardless of what protocol that is used. The following table list some of the main protocols supported by Alfresco and links to more detailed documentation. Protocol

Description

HTTP

The main protocol used to access Standard in Enterprise and Alfresco content repository via for Community. example the Alfresco REST APIs.

WebDAV

Web-based Distributed Authoring and Versioning is a set of HTTP extensions that lets you manage files collaboratively on web servers.

Standard in Enterprise and Community.

FTP

File Transfer Protocol - standard network protocol for file upload, download and manipulation. Useful for bulk uploads and downloads.

Standard in Enterprise and Community.

CIFS

Common Internet File System allows the projection of Alfresco as a native shared drive. Any client that can read or write to file drives can read and write to Alfresco, allowing the commonly used shared file drive to be replaced with an ECM system, without users knowing.

Standard in Enterprise and Community.

SPP

Enables Alfresco to act as a Microsoft SharePoint Server. Allows Microsoft Office users to access documents within the Alfresco repository.

Supported as part of Alfresco Office Services (AOS). Enterprise only. Community versions have support for the older SharePoint Protocol Support.

Alfresco Office Services

Alfresco Office Services (AOS) allow you to access Alfresco directly from all your Microsoft Office applications.

Enterprise only.

6 Alfresco 5.1

Support Status

Developer Guide

Protocol

Description

Support Status

CMIS

Alfresco fully implements both the Standard in Enterprise and CMIS 1.0 and 1.1 standards to Community. allow your application to manage content and metadata in an onpremise Alfresco repository or Alfresco in the cloud.

IMAP

Internet Message Access Standard in Enterprise and Protocol - allows access to email Community. on a remote server. Alfresco can present itself as an email server, allowing clients such as Microsoft Outlook, Thunderbird, Apple Mail and other email clients to access the content repository, and manipulate folders and files contained there.

SMTP

It is possible to email content into the repository (InboundSMTP). A folder can be dedicated as an email target.

Standard in Enterprise and Community.

Related Links Architecture on page 3

Repository concepts It is important as a developer to have a good understanding of the fundamental concepts of Alfresco when implementing extensions. Important concepts covered include repository, nodes, stores, types, aspects and so on. Key Concepts All files that are stored in the Alfresco content management system are stored in what is referred to as the repository. The repository is a logical entity that consists of three important parts: 1. The physical content files that are uploaded 2. The index files created when indexing the uploaded file so it is searchable 3. The metadata/properties for the file, which are stored in a relational database management system (RDBMS). When a file is uploaded to the Alfresco repository it is stored on disk in a special directory structure that is based on the date and time of the upload. The file name is also changed to the UUID (Universally Unique Identifier) assigned to the file when it is added to the repository. The file's metadata is stored in an RDBMS such as PostgreSQL. Indexes are also stored on the disk. When the file is added to the repository it is stored in a folder, and in the Alfresco a folder has domain specific metadata, rules, and fine grained permissions. The top folder in the Alfresco repository is called Company Home, although it will be referred to with the name repository in the Alfresco Share user interface. Logical Structure All the files and folders that are uploaded and created in the Alfresco repository are referred to as nodes. Some nodes, such as folders and rules, can contain other nodes (and are therefore known as container nodes). Nodes can also be associated with other nodes in a peer to peer relationship, in a similar fashion to how an HTML file can reference an image file. All nodes live in a Store. Each store has a root node at the top, and nodes can reference specific files, as shown in the following diagram:

Developer Guide 7

Developer Guide

Stores Overview The Repository contains multiple logical stores. However, a node lives only in one store. Most of the stores are implemented as data in the connected RDBMS, only the Content Store is implemented so as to store items on disk:

The main stores The Working Store (workspace://SpacesStore) contains the metadata for all active/live nodes in the Repository. This store is implemented using a database (RDBMS). The Content Store contains the physical files uploaded to the Repository and is located in the {Alfresco install dir}/alf_data/contentstore directory on the filesystem by default, but can also be configured to use other storage systems, for example, Amazon S3. It is also possible to define content store policies for storing files on different storage systems, effectively defining more than one physical content store.

8 Alfresco 5.1

Developer Guide

Whenever a node is deleted, the metadata for the node is moved to the Archive Store (archive://SpacesStore), which uses the configured database. The physical file for a deleted node is moved (by default after 14 days) to the {Alfresco install dir}/alf_data/ contentstore.deleted directory, where it stays indefinitely. However, a clean-up job can be configured to remove the file at a certain point in time (referred to as eager clean-up). When the versionable aspect is applied to a node, a version history is created in the Version Store (workspace://lightWeightVersionStore). Versioned node metadata is stored in the database and files remain in the {Alfresco install dir}/alf_data/contentstore directory. Versioning is not applicable to folder nodes. The System Store is used to save information about installed Alfresco extension modules. Content Store Implementation When considering file storage, it should be noted that files added to Alfresco can be of almost any type, and include images, photos, binary document files (Word, PPT, Excel), as well as text files (HTML, XML, plain text). Some binary files such as videos and music files can be relatively large. Content store files are located on the disk, rather than in the database as BLOBs. There are several reasons for this: 1. It removes incompatibility issues across database vendors. 2. The random file access support (as required by CIFS and other applications) cannot be provided by database persistence without first copying files to the file system. 3. Possibility of real-time streaming (for direct streaming of files to browser). 4. Standard database access would be difficult when using BLOBs as the most efficient BLOB APIs are vendor-specific. 5. Faster access. Content Store Selectors The content store selector provides a mechanism to control the physical location on disk for a content file associated with a particular content node. This allows storage polices to be implemented to control which underlying physical storage is used, based on your applications needs or business policies. For example, it is possible to use a very fast tier-1 Solid State Drive (SSD) for our most important content files. Then, based on business policies that have been decided, gradually move the data, as it becomes less important, to cheaper tier-2 drives such as Fiber Channel (FC) drives or Serial ATA drives. In this way, it is possible to manage the storage of content more cost effectively:

Store Reference When working with the APIs a store is accessed via its store reference, for example workspace://SpacesStore. The store reference consists of two parts: the protocol and the identifier. The first part (for example workspace) is called the protocol and indicates the content you are interested in, such as live content (workspace://SpacesStore) or archived content (archive://SpacesStore). The second part is the identifier (the type of store) for the store, such

Developer Guide 9

Developer Guide

as SpacesStore, which contains folder nodes (previously called spaces) and file nodes data, or for example lightWeightVersionStore that contains version history data. The reason some things are referred to as spaces (for example SpacesStore) is that in previous versions of Alfresco a folder used to be called a space. The Share user interface has generally been changed to use the name folder instead of the name space. However, there is functionality, such as Space Templates, that still uses the term "space". A space can simply be thought of as a folder. Node Information A node usually represents a folder or a file. Each store also contains a special root node at the top level with the type sys:store_root. The root node can have one or more child nodes, such as the Company Home folder node. Each node has a primary path to a parent node and the following metadata: • Type: a node is of one type, such as Folder, File, Marketing Document, Rule, Calendar Event, Discussion, Data List and so on. • Aspects: a node can have many aspects applied, such as Versioned, Emailed, Transformed, Classified, Geographic and so on. • Properties: both types and aspects define properties. If it is a file node then one of the properties points to the physical file in the content store. • Permissions: access control settings for the node. • Associations: relationships to other nodes (peer or child). Node Reference A node is uniquely identified in the Repository via its node reference, also commonly referred to as NodeRef. A node reference points to a store and a node in that store. A node reference has the following format: {store protocol://store identifier}/UUID such as for example workspace://SpacesStore/986570b5-4a1b-11dd-823c-f5095e006c11. The first part is the store reference and the second part is a Universally Unique Identifier (UUID) for that store. Node references are used a lot in the available APIs so it is good to have an idea of how they are constructed. Node Properties The node properties, also referred to as the node's metadata, contains the majority of the information for a node. The sys:store-protocol, sys:store-identifier, and sys:nodeuuid properties contains all the data needed to construct the NodeRef, uniquely identifying the node. The special property called cm:content points to where the physical content file is stored on disk (unless it is a folder or other contentless node type). All properties are either contained in a type or in an aspect defined in a content model. When a node is created some properties are automatically set by the system and cannot be easily changed, they are called audit properties (from the cm:auditable aspect) and are Created Date, Creator, Modified Date, Modifier, and Accessed. Defining new domain specific node properties, together with the types and aspects that contain them, is the primary way of classifying a node so it can be easily found via searches. Metadata/Property Extractors Some of the properties of a file node are set automatically when it is uploaded to the Repository, such as author. This is handled by metadata extractors. A metadata extractor is set up to extract properties from a specific file MIME type. There are numerous metadata extractors available outof-the-box covering common MIME types such as MS Office document types, PDFs, Emails, JPEGs, HTML files, DWG files and more. The metadata extractors are implemented via the Tika library, although custom metadata extractors are available. Each metadata extractor implementation has a mapping between the properties it can extract from the content file, and what content model properties that should be set as node metadata. Node Associations

10 Alfresco 5.1

Developer Guide

There are two types of associations: • Parent to Child associations - these are for example folder to file associations where deleting the folder will cascade delete its children. • Peer to Peer - an example could be article to image associations where deleting the article does not affect the related image node(s). These associations are also referred to as source to target associations. QName All properties are defined within a specific content model, which also defines a unique namespace. For example, a property called description can be part of many namespaces (content models). To uniquely identify what description property is being referenced, a fully qualified name, or a QName, is used. A QName has the following format: {namespace URL}property local name, for example: {http://www.alfresco.org/model/content/1.0}description

The first part in curly braces is the namespace identifier defining the content model that the property is part of. The second part is the local name of the property (that is description in this case). A QName is used for types, aspects, properties, associations, constraints and so on. The QName for the generic folder type that is part of the out-of-the-box document content model is cm:folder. Note the use of cm to denote the namespace. Each content model defines a prefix for each namespace that is used in the content model. Each type, aspect, property and so on in the content model definition uses the namespace prefix instead of the full namespace URL. You will also use the prefix when referring to entities such as types, aspects, properties, in the different APIs. Permissions Permissions are set up per node and a node can inherit permissions from its parent node. A Role (Group) Based Access Control configuration is the preferred way to set up permissions in the repository. However, permissions can also be set for an individual user. Groups and users can be synchronized with an external directory such as LDAP or MS Active Directory. Some groups are created automatically during installation: • EVERYONE – all users in the system • ALFRESCO_ADMINISTRATORS – administrators with full access to everything in the Repository. • ALFRESCO_SEARCH_ADMINISTRATORS – can access the Search Manager tool and set up search filters (facets). • SITE_ADMINISTRATORS – can access the Site Manager tool and change visibility of sites, delete sites, and perform site related operations. • E-MAIL_CONTRIBUTORS – users that can send email with content into Alfresco. Permission settings involve three entities:

There are a number of out-of-the-box roles: 1. Consumer

Developer Guide 11

Developer Guide

2. Contributor 3. Editor 4. Collaborator 5. Coordinator Whenever a Share site is created there are also four associated groups created that are used to set up permissions within the site. In the repository, groups are prefixed with GROUP_ and roles with ROLE_, this is important when referring to a group or role when using one of the APIs. A Site is a collaboration area in Alfresco Share where a team of people can collaborate on content. Owner The Repository contains a special authority called owner. Whoever creates a node in the repository is called the owner of the node. Owner status overrides any other permission setting. As owner you can do any operation on the node (basically the same as being coordinator/admin). Anyone with Coordinator or Admin status can take ownership of a node (cm:ownable is then applied). Folder Node and File Node Overview The diagram illustrates a typical folder node with a child file node when it has been classified with the out-of-the-box default document content model:

Related Links Architecture on page 3

Mini Glossary Terms and concepts used when developing for Alfresco. Term

Description

Actions

Actions typically work in conjunction with Rules. When creating a rule you specify the action to be carried out when the rule is activated. There are standard actions, but you can also create custom actions. Custom actions are implemented in Java as Spring beans.

12 Alfresco 5.1

Developer Guide

Term

Description

Aspects

While nodes must be of a single Type, they can have multiple Aspects applied to them. Dublin Core, Taggable, EXIF, Geographic, Emailed are all examples of aspects. Also a single aspect can be applied to multiple types.

Associations

Relationships between Types are modeled with Associations. There are two types: Child Associations and Peer Associations.

Attributes

Attributes provide a global means of storing keyvalue data. Whereas properties are attached to a node, attributes are system-wide, and not stored per-node. They can be quickly searched for without the need for an index and are cluster-safe.

Auditing

Auditing allows you to track events that occur in Alfresco ECM. The events that you audit are completely configurable.

Configuration

Alfresco Platform provides many points at which the configuration of the system can be changed. For example, changes may be made to alfrescoglobal.properties or many of the other configuration files. In addition, the Share web client is highly configurable.

Content

This is the piece of content to be stored in the repository. It could be a Word document, a PDF, a PNG image file, an audio file and so on. Note that the content itself will be stored on the file system, while its corresponding node, containing metadata, will be stored in an RDBMS.

Content Model

The content model describes the nodes and the hierarchical relationship between them, as well as any constraints that may exist. For example, nodes that are of container type can contain other nodes.

Content Renditions

Renditions are manipulations of content that typically involves some content transformation, followed by some other operation such as crop or resize. For example, you might have a PDF document, which you might convert the first page of to a PNG, and then crop and resize that image to create a thumbnail view of the document. The key service is the Rendition Service.

Content Store

The Alfresco repository has multiple content stores. Typically this would include a main content store, an encrypted content store, an archive content store (for deleted items), and a version store (to hold previous versions of documents). It is also possible for developers to create custom content stores for specific purposes.

Developer Guide 13

Developer Guide

Term

Description

Content Transformation

Content transformation transforms one format of content into another. There are numerous applications of this, such as converting content into plain text for indexing and generating PDF versions of Word files. Transformations can be chained together, for example DOC to PDF using LibreOffice. Key service is the ContentTransformation Service.

Extension

Extensions can be thoughts of as server-side additions to Alfresco. There are two main types of extension: Platform and Share. Each of these extension types are fully described in this documentation, along with all officially supported extension points.

Events

Data structures created on various changes within the repository, such as name change of a piece of content. There are three types of Event:

Indexing

1.

Inbound event - content arriving into a folder

2.

Outbound event - content leaving a folder

3.

Update event - content being modified

As content is added to the Alfresco ECM it is indexed by an indexer such as Solr. Solr indexes both meta data and the plain text content of files added. The content model defines the metadata (aspects, properties, types, associations) that are to be indexed via the element. The indexes can be queried using a variety of query languages, including: •

fts-alfresco

•

storeroot

•

noderef

•

xpath

•

lucene

•

cmis-strict

•

cmis-alfresco

•

db-afts

•

db-cmis

Queries can be executed from JavaScript and Java code, and also in the Node Browser (available under Admin Tools in Share). Nodes

Each piece of content in the repository has a node associated with it. The node contains information about the content, such as its metadata and location within the content store. The node is stored in a RDBMS such as PostgreSQL, the content itself is stored on the file system.

Predefined Content Model

There are pre-defined content models provided out-of-the-box, these include Folder/Document hierarchy, Dublin Core, blogs, Wiki, Sites.

14 Alfresco 5.1

Developer Guide

Term

Description

Policies

These are event handlers triggered by certain node events for either all nodes or just nodes of a specific type.

Metadata

Most content has metadata associated with it. For example, photographs have EXIF metadata. Word documents would have Author, Creation Date, and so on. The metadata provides very useful information for document discovery, without the overhead of having to extract and process the full content of a document.

Metadata extraction

Content type (mimetype) can automatically be identified for the standard types by Tika. This metadata can be extracted from the content and copied into the content's associated node (properties). For custom content types it is possible to create Custom metadata extractors. Key service is the MetadataExtractor Service. You can also create custom metadata extractors.

Mimetypes

The mimetype essentially identifies the type of content. Alfresco is able to automatically identify content types and establish mimetype (using Tika). It is also possible to create custom content identification through custom mimetypes.

Module

A module is the format in which an extension is packaged.

Property

Properties are named items of metadata associated with a Type. Each Property is of a specific data type (such as Text or Date). Constraints can be applied to restrict the value of a Property.

Repository

This is where content is stored, and can be thought of as the content stores and all the related services. It consists of the filesystem or storage service where the content is stored and a database containing metadata. See Repository Concepts for an overview.

Rules

Declarative definition of processes based on addition, update, or removal of nodes with respect to folders (think email rules for content). These are set up for a folder in Share. See documentation and videos on applying rules to folders. Note that Rules can be filtered based on conditions/criteria: •

All items (no filter)

•

Items with a specific mimetype (for example .doc, .pdf)

•

Contained in a category

•

Specific content type applied to a specific aspect file name pattern (for example *context.xml)

Boolean NOT can be used (for example not .pdf). There are no limits to the number of conditions that can be applied to each Rule.

Developer Guide 15

Developer Guide

Term

Description

Type

A node is always of a single Type. A Type is similar to a class in Object-Oriented Programming, Types can be inherited from a parent Type in the content model.

Related Links Architecture on page 3

Alfresco SDK 2.2.0 This documentation covers version 2.2.0 of the Alfresco SDK. The Alfresco SDK is a Maven based development kit that provides an easy to use approach to developing applications and extensions for Alfresco. With this SDK you can develop, package, test, run, document and release your Alfresco extension project. It is important to note that while previous versions of the Alfresco SDK were based around Ant, the latest versions of the SDK are based on Maven. Links to documentation for previous versions are available on this page. This is the PDF version of this documentation and is not complete. Please refer to Alfresco Documentation online for access to the complete set of documentation. The Alfresco SDK 2.2 includes a number of Maven archetypes. These archetypes aim to provide a standardized approach to development, release, and deployment of Alfresco extensions.

Project documentation, website, and support From version 2.0 and up, releases for the Alfresco SDK are available in Maven Central. The Alfresco SDK source code is hosted on GitHub. The Alfresco SDK issue tracking is hosted on GitHub. The Alfresco SDK forum for support is hosted on Alfresco Forums. Related Links Developer Guide on page 3 What's new? on page 16 Introduction to the Alfresco SDK on page 18 Getting Started with the Alfresco SDK on page 23 Maven Archetypes - Command Reference on page 44 Rapid Application Development (RAD) on page 52 Advanced Topics on page 86 Upgrading on page 122 Using the REST API Explorer on page 153 Using MySQL on page 156

What's new? New features in this version of the Alfresco SDK.

What's new in Alfresco SDK 2.2.0 • Support for Alfresco 5.1 • Alfresco REST API Explorer is now available with the run profile (http://localhost:8080/apiexplorer)

16 Alfresco 5.1

Developer Guide

• All-In-One AMP module names and ID now includes AIO name to make them unique • Aligned Module version with Artifact version - 5.0 and 5.1 supports SNAPSHOT versions in module.properties

• Numerous bug fixes. See the release notes for details. • Issues: you will have to run without Spring Loaded with AIO and Repo AMP, only works with Share AMP at the moment.

What's new in Alfresco SDK 2.1.1 • Reintroduce support for Java 7 • Numerous bug fixes. See the release notes for details.

What's new in Alfresco SDK 2.1 • Support for Solr 4 • Regression testing Share Webapp with Alfresco Share Page Object (PO) tests • Functional testing of Custom Pages with Alfresco Share PO • Rapid Application Development (RAD) improvements: • New alfresco:refresh-repo goal for alfresco-maven-plugin for automatic refresh of repository (alfresco.war) • New alfresco:refresh-share goal for alfresco-maven-plugin for automatic refresh of Share (share.war) • Automatic JavaScript compression • Custom package name can be used when generating projects • Records Management profile 'rm' removed, now included as other AMPs in the repository and Share WAR POMs • Run script for Windows now available (run.bat) • Upgraded to Alfresco Community Edition 5.0.d and Enterprise 5.0.1 (JDK8) • Fixed DB initialization error (dbObject cannot be null) • Fixed blank Admin Console bug

What's new in Alfresco SDK 2.0 • Support for Alfresco 5.0 • Name changed from Maven Alfresco SDK to Alfresco SDK. • New Share AMP archetype. • RAD in Eclipse and IntelliJ. • Now requires Maven 3.2.2 • RAD with Spring Loaded. • Support for JRebel has been deprecated. • Introduction of enterprise profile option -Penterprise.

What was new in Alfresco SDK 1.1.1 • Bug fixes.

What was new in Alfresco SDK 1.1.0 • Runs in Tomcat7 (replaces Jetty) • Remote running of JUnit

Developer Guide 17

Developer Guide

• JRebel integration • Improved IDE integration

What was in Alfresco SDK 1.0.x • Use of Alfresco POMs • Relied on a number of components: • The SDK parent POM providing full Alfresco project lifecycle feature, to be added as a in your projects • Archetypes like the AMP or all-in-one providing sample project to kickstart your Alfresco development and boost it with best practices • The Alfresco Maven Plugin to manage AMP packaging and dependencies • Alfresco Platform Distribution POM can (optionally) be used to provide centralized on a particular Alfresco version / edition (Community Edition / Enterprise) • The Alfresco Artifacts Repository provides backing for this SDK. Check the Alfresco Wiki for Community Edition / Enterprise access information • Embedded Jetty server and H2 database

What was in Maven Alfresco Lifecycle • First implementation of Alfresco Maven SDK (Now deprecated) • No use of Alfresco POMs • Available archetypes and plugins: • maven-alfresco-extension-archetype to create WAR packaged webapps that can provide all Maven lifecycle and features • maven-alfresco-share-archetype to create and manage Alfresco Share customization webapps • maven-alfresco-share-module-archetype to create and manage Alfresco Share custom dashlets, pages as JARs • maven-alfresco-amp-archetype to create maven-amp-plugin managed web apps, which can provide all Maven lifecycle and features to Alfresco modules. The maven-amp-plugin is also used as a replacement to MMT to unpack AMPs into WARs builds, using the Maven dependency mechanism provided by the mavenamp-plugin

• Embedded Jetty server and H2 database to run Alfresco or Share • Possible to use Maven standard dependency management to pull in AMPs in your build • Further information Related Links Alfresco SDK 2.2.0 on page 16

Introduction to the Alfresco SDK You will learn about the different Maven Archetypes that can be used to generate Alfresco extension projects. You will learn which SDK version is compatible with which Alfresco version, and you will find links to some useful community resources.

18 Alfresco 5.1

Developer Guide

Related Links Alfresco SDK 2.2.0 on page 16 Introduction to Maven archetypes on page 19 Compatibility matrix on page 22 Community resources on page 22

Introduction to Maven archetypes There are three Maven archetypes that can be used to generate Alfresco extension projects. The following project types, and archetypes, are available: • Alfresco Repository AMP: this archetype is used to create extensions for the Alfresco Repository Web Application (alfresco.war) in the form of Alfresco Module Packages (AMP). • Alfresco Share AMP: this archetype is used to create extensions for the Alfresco Share Web Application (share.war) in the form of AMPs. • Alfresco all-in-one (AIO): this archetype is a multi-module project that leverages the Alfresco SDK's powerful capabilities to customize and run the full Alfresco platform embedded with all its components. The archetype does not require additional downloads and provides a perfect starting point for full-blown Alfresco projects. You can view these archetypes when you obtain a list of archetypes from Maven Central: mvn archetype:generate -Dfilter=org.alfresco:

Note the use of a filter to display only archetypes in the namespace org.alfresco. Related Links Introduction to the Alfresco SDK on page 18 Repository AMP archetype on page 19 Share AMP archetype on page 20 All-in-One archetype on page 21

Repository AMP archetype The Alfresco Repository (Repo) AMP Archetype generates a sample project for managing Alfresco Repository extensions/customizations. These extensions are packaged as Alfresco Module Packages (AMP). This archetype should be used to extend the Alfresco Repository web application (alfresco.war). The following are typical use-cases for when this archetype should be used: • You work in a bigger team and want to develop, tag, and release a Repo module separately from the main Alfresco Extension project (All-in-One) that it is included in. • You want to add, and contain, an extra Repo module in an All-In-One Project (useful when you don't have a Nexus artifacts repo to which you can release individual repo AMPs). • You intend to build an Add-On, Component, Module etc that should be distributed independently. If you intend to build an extension for the Alfresco Share web application, use the Share AMP archetype instead. The main features of this archetype are: • AMP packaging - the supported packing type for Alfresco extensions.

Developer Guide 19

Developer Guide

• AMP dependency management in Maven. • Installation of AMPs into an Alfresco WAR. • Sample repository web script demonstrating how to implement a custom REST-based API. • Content Model Skeleton XML file ready to be filled in with your domain specific content model. • AMP Unit Testing support. Just run the standard mvn test and see your src/test/java Alfresco unit tests run. An sample Unit Test is provided in this archetype. • Run embedded in Tomcat with an embedded H2 database for demo purposes (-Pamp-towar), rapid application development and integration testing. This is not a supported stack, so it should only be used for development purposes. • Support for (remote) Junit and integration testing and Rapid Application Development. This uses spring-loaded. Project can easily be launched for this scenario using run.sh. • Easy to integrate with an IDE environment such as Eclipse and IntelliJ IDEA. Related Links Introduction to Maven archetypes on page 19

Share AMP archetype The Alfresco Share AMP Archetype generates a sample project for managing Alfresco Share extensions/customizations. These extensions are packaged as Alfresco Module Packages (AMP). This archetype should be used to extend the Alfresco Share web application (share.war). The following are typical use-cases for when this archetype should be used: • You work in a bigger team and want to develop, tag, and release a Share UI module separately from the main Alfresco Extension project (All-in-One) that it is included in. • You want to add, and contain, an extra Share UI module in an All-In-One Project (useful when you don't have a Nexus artifacts repo to which you can release individual Share UI modules). • You intend to build an Add-On, Component, Module etc that should be distributed independently. If you intend to build an extension for the Alfresco Repository web application, use the Repository AMP archetype instead. The main features of this archetype are: • AMP packaging - the supported packing type for Alfresco extensions. • AMP dependency management in Maven. • Installation of AMPs into an Share WAR. • Sample Aikau page and widget to demonstrate how to develop new pages for the Alfresco Share UI. • AMP Unit Testing support. Just run the standard mvn test and see your src/test/java Alfresco unit tests run. An sample Unit Test is provided in this archetype. • Run embedded in Tomcat for demo purposes (-Pamp-to-war), rapid application development and integration testing. Requires a running Alfresco Repository on localhost:8080. • Easy to integrate with an IDE environment such as Eclipse and IntelliJ IDEA.

20 Alfresco 5.1

Developer Guide

Related Links Introduction to Maven archetypes on page 19

All-in-One archetype The Alfresco All-in-One (AIO) Archetype is a multi-module project, leveraging Alfresco SDK's powerful capabilities to customize and run the full Alfresco platform embedded with all its components. The archetype does not require additional downloads, such as an Alfresco installer, and provides a perfect starting point for full-blown Alfresco projects where the final artifacts should be the customized alfresco.war and share.war. The following are typical use-cases for when this archetype should be used: • You are going to start on a project for a client and need an Alfresco extension project that can produce the final customized Alfresco WAR and Share WAR artifacts. • Your project needs access to the full regression testing suite for the Alfresco Share UI. • Your project needs access to the functional testing based on the Alfresco Share Page Object (PO) library. • When testing with the RAD features you need Solr to be running. Note that if you are going to develop an addOn, reusable component, module, and so on, that should be distributed independently, then have a look at the AMP projects instead. For Alfresco repository extensions see Repository AMP and for Alfresco Share extensions see Share AMP. The main features of the AIO archetype are: • AMP packaging for repository and share extensions - the supported packing type for Alfresco extensions. • AMP dependency management in Maven. • Automatic installation of AMPs into Alfresco WAR and Share WAR. • Easy to include extra AMPs and have them included in the WARs. • Out-of-the-box Alfresco extensions such Records Management (RM), SharePoint Protocol (SPP), Media Management etc easily included in the same way as custom AMPs for consistency. • AMP Unit Testing support. Just run the standard mvn test and see your src/test/java Alfresco unit tests run. An sample Unit Test is provided in this archetype. • Alfresco Share Regression Testing - you don't have to write tests to protect against regression in out-of-the-box Share UI functionality, just use the -Prun,regression-testing profiles • Custom Functional Testing - Utilize the Alfresco Share Page Objects (PO) to write your own custom web page testing (example test included), use the -Prun,functional-testing profiles • Run a full Alfresco stack (that is, alfresco.war, share.war, solr4.war) embedded in Tomcat using the H2 database for demo purposes (-Prun), rapid application development and integration testing. This is not a supported stack, so it should only be used for development purposes. • Support for (remote) Junit and integration testing and Rapid Application Development. This uses spring-loaded. Projects can easily be launched for this scenario using run.sh. • Seamless IDE integration with Eclipse and IntelliJ IDEA. Related Links Introduction to Maven archetypes on page 19

Developer Guide 21

Developer Guide

Compatibility matrix Alfresco SDK has several versions and compatibility with Alfresco versions varies. It is recommended you use the latest version of the Alfresco SDK where possible. The following table shows compatibility between Alfresco SDK and versions of Alfresco. Alfresco Maven Maven Maven SDK 1.1.x version Alfresco SDK 1.0.x Lifecycle (deprecated) (deprecated)

Alfresco SDK 2.0.x

Alfresco SDK 2.1.x

3.2.2 4.1.1.x

Not available

Not available Not available

Compatible Not (but not available supported)

Not available

Alfresco SDK 2.2.x

4.1.x (x Not >= 2) available

Compatible Not available (but not (SDK 1.1.0 does supported) not work with Alfresco 4.1.2-4.1.5 using Solr Search Subsystem. It is possible to use Alfresco 4.1.6 and greater, or use Lucene Search Subsystem)

Not available

Not available Not available

4.2.x

Not available

Not available

Compatible and supported

Not available

Not available Not available

5.0 and Not 5.0.c available

Not available

Not available

Compatible and supported

Not available Not available

5.0.1+ and 5.0.d+

Not available

Not available

Not available

Compatible and supported

Compatible and supported

5.1+ and 5.1.d+

Not available

Not available

Not available

Not available

Not available Compatible and supported

Not available

Note that Alfresco 4.1.x requires Java 6, Alfresco 4.2.x and Alfresco 5.0 require Java 7. Alfresco 5.0.1 and 5.0.d requires Java 7 or 8. Alfresco 5.1.0 and 5.1.d requires Java 7 or 8. Note also that Alfresco SDK works only on Linux, Windows or Mac. Related Links Introduction to the Alfresco SDK on page 18

Community resources Use the community resources that are available to help you master the Alfresco SDK. Some community resources that are worth trying out: Link

Description

Alfresco SDK on GitHub

Where you can clone the code, submit issues and read community documentation.

Order of the Bee

Quoting from the site: We are an independent organization of the Alfresco community. We are here to promote Alfresco Community Edition and aggregate the best from the community for you.

22 Alfresco 5.1

Developer Guide

Link

Description

Mind the Gab

News, thoughts and tutorials from one of the main developers behind the Alfresco SDK.

Getting Started with Alfresco SDK 2

Great article by Jeff Potts about how to get going with SDK 2.

Alfresco SDK 2.0 Deep Dive

Article that takes a look at the "behind the scenes" stuff used by the Alfresco SDK 2.0.

Ole Hejlskov's Alfresco SDK 2.0 Beta screencast

Screencast showing use of the three main archetypes of the SDK in Eclipse. Also demonstrates some important features of the SDK such as hot reloading of code.

Related Links Introduction to the Alfresco SDK on page 18

Getting Started with the Alfresco SDK This information gets you started with the Alfresco SDK. The Alfresco SDK itself does not need to be installed (as it is based around Maven), but there are some prerequisites that will need to be made available. This information is split into three areas: • Installing software that is a prerequisite for running the SDK successfully • Getting the SDK working from the command line • Getting the SDK working from IDEs Related Links Alfresco SDK 2.2.0 on page 16 Before you begin on page 23 Installing and configuring software on page 23 Creating a project on page 30

Before you begin There are some points you need to be aware of before you start using the Alfresco SDK. Some things to do and note before you start: 1. Check the What's New page to orientate yourself to the latest features of the SDK. 2. Check the compatibility matrix to make sure that you have the right version of the SDK for your version of Alfresco. 3. Make sure that you understand the different types of Maven archetypes that are available. Check the Maven Archetypes summary to make sure that you use the right one for your extension. Related Links Getting Started with the Alfresco SDK on page 23

Installing and configuring software Use this information to install and configure the software on which the SDK depends. You'll need to download and install the following tools and libraries, if you don't already have them: 1. The Oracle Java Software Development Kit (JDK) version 8 (or IBM SDK 7.1 if on IBM WebSphere)

Developer Guide 23

Developer Guide

2. Apache Maven 3.2.5+ 3. Spring Loaded (Note. only works with the Share AMP archetype at the moment). Related Links Getting Started with the Alfresco SDK on page 23 Install Spring Loaded on page 24 Install JDK on page 24 Setting JAVA_HOME on page 25 Install Maven on page 26 Setting MAVEN_OPTS & M2_HOME on page 27 Using Alfresco Enterprise (Optional) on page 28 Verify install on page 29

Install Spring Loaded The Alfresco SDK's Rapid Application Development (RAD) features uses Spring Loaded. There are no pre-requisites for this installation. (Note. ONLY works with the Share AMP archetype at the moment). Spring Loaded is a Java agent (represented by a JAR file) that enables class reloading in a running JVM. It will enable you to update a Java file in your Alfresco extension project and then see the effect of the change directly in a running Alfresco-Tomcat-JVM instance without having to re-build JARs, AMPs, and WARs and re-deploying them, saving you loads of time. 1. Download the Spring Loaded JAR from here. 2. Copy JAR to some directory. There is no specific installation needed, just copy the JAR to a permanent place where you can refer to it. You now have the Spring Loaded JAR readily available in a directory. Related Links Installing and configuring software on page 23

Install JDK The Alfresco SDK is based on Maven, which requires the JDK to be installed. This topic steps you through installing the JDK and verifying its installation. There are no pre-requisites for this installation. To use the Alfresco SDK most effectively, and to align with what JDK is used by the default Alfresco versions in the SDK, you need to have Oracle JDK 1.8 installed (or IBM SDK 7.1 if on IBM WebSphere). Maven requires that the JDK be installed - the Java run-time alone is not sufficient. Checking for the availability of the JDK. 1. Check if you have the JDK already installed. Go to your command line and type the following command: javac -version

You will see a message such as the following, if you have the JDK installed: javac 1.8.0_45

Make sure you use javac when you test if JDK is installed and not java, which tests if JRE is installed.

24 Alfresco 5.1

Developer Guide

If you get "command not found" you need to install the JDK. Also if you have a version of the JDK prior to 1.8 you will need to install 1.8 or above (or IBM SDK 7.1 if on IBM WebSphere). It is possible to have multiple versions of the JDK installed (and multiple Java run-times). You will later see how you can configure your JAVA_HOME variable so that Maven uses the correct version of the JDK. Downloading the JDK. 2. Download the JDK from the Oracle JDK site. Installing the JDK. 3. Carefully review the Oracle JDK 8 installation guide as appropriate for your system. 4. Install the JDK, following the Oracle instructions. Verifying the JDK is successfully installed. 5. Go to your command line and type the following command: javac -version

This will display information such as the following: javac 1.8.0_45

To be extra sure you should also check your Java run-time by entering the following command: java -version

This will display information such as the following: java -version java version "1.8.0_45" Java(TM) SE Runtime Environment (build 1.8.0_45-b14) Java HotSpot(TM) 64-Bit Server VM (build 25.45-b02, mixed mode)

Double check that the version of Java installed is correct (1.8). You now have JDK 1.8 installed and you have verified that you are running the correct version of Java. Related Links Installing and configuring software on page 23

Setting JAVA_HOME Before using the Alfresco SDK, you need to set your JAVA_HOME environment variable to a suitable value, using the correct mechanism for your operating system. Setting the JAVA_HOME environment variable ensures that the correct JDK is accessed. This is especially important where you have multiple JDKs installed on your system. 1. On Mac OS X you can edit your .bash_profile file and add something similar to the following (the exact version you are using may vary): export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.8.0_45.jdk/ Contents/Home

Restart the terminal session or run source .bash_profile to activate the environment variable. Note that the actual value you specify here will depend on which JDK you have installed, and the resultant directory name. 2. On Linux you can edit your .bashrc file and add something similar to the following: export JAVA_HOME=/usr/lib/jvm/java-8-oracle

Developer Guide 25

Developer Guide

Restart the terminal session or run source .bashrc to activate the environment variable. Note that the actual value you specify here will depend on which JDK you have installed, and the resultant directory name. 3. On Windows, the exact procedure for setting environment variables varies depending on the version of Windows you are running. For example, the procedure for Windows XP can be found in the Microsoft Knowledgebase. Note that the actual value you specify here will depend on which JDK you have installed, and the resultant directory name. 4. Ensure that the JAVA_HOME environment variable is set correctly, using a method suitable for your system. For example, on Mac OS X and Linux you can enter the following command: $ env |grep JAVA_HOME JAVA_HOME=/usr/lib/jvm/java-8-oracle

You will see the value that JAVA_HOME has been set to. Ensure that the result matches the value you specified in your shell configuration file (such as .bashrc). If you are on Windows you can use a command such as SET J to display environment variables starting with 'J'. Your JAVA_HOME environment variable is now set, and you have verified it is reflected in your environment. Related Links Installing and configuring software on page 23

Install Maven The Alfresco SDK is now based around Maven (formerly it used Ant). To use the Alfresco SDK you need to have Maven installed. To be able to use Maven you need to have a suitable JDK installed. For this version of the SDK you should have JDK 1.8 installed (or IBM SDK 7.1 if on IBM WebSphere). To use the Alfresco SDK you need to have Maven installed. The version required is 3.2.5 and above. Check for the availability of Maven. 1. First, check to see if you already have the correct version of Maven installed. On your command line enter the following command: mvn --version

If you get "command not found", or you have a version of Maven less than 3.2.5, you will need to install Maven or upgrade to 3.2.5 or above. In this case it is recommended you download the latest version of Maven (3.2.5+) from the official Maven website. Downloading Maven. 2. Download Maven from the Apache Maven project web site. Installing Maven. 3. Carefully review the platform-specific installation instructions in the Installing Maven Sonatype documentation. 4. Install Maven using the platform-specific instructions provided in the Maven documentation. Verifying Maven is correctly installed.

26 Alfresco 5.1

Developer Guide

5. Run the following command to verify Maven is correctly installed: mvn --version

This will display information such as the following: Apache Maven 3.3.3 (7994120775791599e205a5524ec3e0dfe41d4a06; 2015-04-22T12:57:37+01:00) Maven home: /home/martin/apps/apache-maven-3.3.3 Java version: 1.8.0_45, vendor: Oracle Corporation Java home: /usr/lib/jvm/java-8-oracle/jre Default locale: en_GB, platform encoding: UTF-8 OS name: "linux", version: "3.13.0-58-generic", arch: "amd64", family: "unix"

Check that the correct versions of Maven and the JDK are being used. If Maven is not using the correct version of the JDK, make sure you have set your JAVA_HOME environment variable, as described in the previous tutorial. You have now installed Maven and verified that it is the correct version and is using the correct version of the JDK. Related Links Installing and configuring software on page 23

Setting MAVEN_OPTS & M2_HOME Before using the Alfresco SDK, you need to set your MAVEN_OPTS and M2_HOME environment variables to suitable values using the correct mechanism for your operating system. Setting M2_HOME specifies the home of Maven and is used by the script mvn (or mvn.bat on Windows). MAVEN_OPTS is used to configure a bit of extra memory for Maven as it will run an embedded Apache Tomcat application server with Alfresco Repo, Share, and Solr web applications deployed. It also sets the Spring Loaded Java Agent so it is available during Rapid Application Development (RAD). Setting Variables. 1. On Mac OS X you can edit your .bash_profile file and add the following: export M2_HOME=/home/martin/apps/apache-maven-3.3.3 export MAVEN_OPTS="-Xms1024m -Xmx1G -XX:PermSize=1024m -noverify"

Spring Loaded ONLY works with the Share AMP archetype at the moment. If you are configuring MAVEN_OPTS to run a Share AMP project set MAVEN_OPTS="Xms1024m -Xmx1G -XX:PermSize=1024m -javaagent:/home/martin/libs/ springloaded-1.2.5.RELEASE.jar -noverify"

Remove -XX:PermSize=1024m if you are using JDK 8, it is only needed for JDK 7. Refer to previous installation sections for in what directory Maven was installed and in what directory Spring Loaded was installed. Restart the terminal session or run source .bash_profile to activate the environment variables. 2. On Linux you can edit your .bashrc file and add the following: See step 1 for Mac OS, do the same thing for Linux. Restart the terminal session or run source .bashrc to activate the environment variable. 3. On Windows, the exact procedure for setting environment variables varies depending on the version of Windows you are running. For example, the procedure for Windows XP can be found in the Microsoft Knowledgebase. set M2_HOME=C:\Tools\apache-maven-3.3.1

Developer Guide 27

Developer Guide

set MAVEN_OPTS=-Xms256m -Xmx1G -XX:PermSize=1024m -noverify

Spring Loaded ONLY works with the Share AMP archetype at the moment. If you are configuring MAVEN_OPTS to run a Share AMP project set MAVEN_OPTS=Xms256m -Xmx1G -XX:PermSize=1024m -javaagent:C:\Tools\spring-loaded \springloaded-1.2.5.RELEASE.jar -noverify

Remove -XX:PermSize=1024m if you are using JDK 8, it is only needed for JDK 7. If the path to the Spring Loaded JAR contains spaces, then you might need to double quote it like -javaagent:"C:\My Tools\spring-loaded \springloaded-1.2.5.RELEASE.jar". Refer to previous installation sections for in what directory Maven was installed and in what directory Spring Loaded was installed. Restart the Windows terminal/console session. Verifying Variables. 4. Ensure that the MAVEN_OPTS and M2_HOME environment variables are set correctly, using a method suitable for your system. For example, on Mac OS X and Linux you can enter the following command: $ env|egrep "M2|MAV" MAVEN_OPTS=-Xms256m -Xmx1G -XX:PermSize=1024m -noverify M2_HOME=/home/martin/apps/apache-maven-3.3.3

Ensure that the result matches the value you specified in your shell configuration file (such as .bashrc). If you are on Windows you can use a command such as set M to display environment variables starting with 'M'. C:\Users\mbergljung>set M M2_HOME=C:\Tools\apache-maven-3.3.1 MAVEN_OPTS=-Xms256m -Xmx1G -XX:PermSize=1024m -noverify

Your MAVEN_OPTS and M2_HOME environment variables are now set. Feel free to increase the specified memory settings if required, for example, if you get "out of memory" errors when running your projects. Related Links Installing and configuring software on page 23

Using Alfresco Enterprise (Optional) By default the Alfresco SDK will use Alfresco Community Edition artifacts but it can be configured to use Enterprise artifacts. This requires access credentials for the Alfresco Private Repository, and modification of several Maven configuration files. To obtain access to the Alfresco Enterprise repository located here, refer to this knowledge base article. If you do not have access to this portal then contact your Alfresco technical representative within your company, or Alfresco directly.

Accessing the Alfresco Private Repository The first matter to consider is to ensure that you have credentials for the Alfresco Private Repository, where the Enterprise artifacts are stored. In fact the private repository also includes all public artifacts too. Once you have suitable credentials you need to add support for Alfresco private repository to your configuration. This would typically be done by adding your access credentials to the settings.xml contained in your ~/.m2 directory (for Linux and OS X). On Windows 7 and Vista this resolves to \Users\ and on XP it is \Documents and Settings\\.m2.

28 Alfresco 5.1

Developer Guide

This procedure is explained in detail in the tutorial Configuring access to the Alfresco Private Repository. Related Links Installing and configuring software on page 23 Configuring access to Alfresco Private Repository on page 29

Configuring access to Alfresco Private Repository In order to be able to utilize Enterprise artifacts, it is necessary to allow Maven access to the Alfresco Private Artifacts Repository, where the Enterprise artifacts are maintained. You need to have permission to access the Alfresco private repository. Enterprise customers can obtain access credentials from Alfresco. In order to allow Maven access to the Alfresco Private Repository, you must add your credentials to the Maven configuration. This is usually done by adding an entry to the settings.xml file, located in your .m2 directory. 1. Obtain access credentials for the Alfresco Private Repository from Alfresco. This is only available for Enterprise-level customers. 2. Change into your Maven configuration directory. For Linux and Mac OS X that will most likely be ~/.m2 for a configuration on a per-user basis, or for global configuration in /conf/. On Windows this would be located in %USER_HOME%/.m2/ for a per-user configuration, and %M2_HOME%/conf for a global configuration. 3. Load settings.xml into your editor. Add the following new server configuration in the section: alfresco-private-repository username password

You will need to replace the placeholder text with your real username and password as allocated by Alfresco. The id value should not be changed as it is used in the Alfresco SDK project build files to specify the Enterprise artifacts Maven repository. It is possible to use encrypted passwords here. See the official Maven documentation for details on how to do this. At this point you have configured Maven to have access to the Alfresco Private Repository. Related Links Using Alfresco Enterprise (Optional) on page 28

Verify install Before proceeding to use the Alfresco SDK, you should do one final check of your system to ensure you have the prerequisites correctly installed. Check you have the JDK and Maven correctly installed, and the correct versions of both, and that Maven is configured to use the correct version of the JDK. Check your configuration by running the command mvn --version and listing Maven environment. This will display information similar to the following: $ mvn --version Apache Maven 3.3.3 (7994120775791599e205a5524ec3e0dfe41d4a06; 2015-04-22T12:57:37+01:00) Maven home: /home/martin/apps/apache-maven-3.3.3 Java version: 1.8.0_45, vendor: Oracle Corporation Java home: /usr/lib/jvm/java-8-oracle/jre

Developer Guide 29

Developer Guide

Default locale: en_GB, platform encoding: UTF-8 OS name: "linux", version: "3.13.0-58-generic", arch: "amd64", family: "unix" $ env|egrep "M2|MAV" MAVEN_OPTS=-Xms256m -Xmx1G -noverify M2_HOME=/home/martin/apps/apache-maven-3.3.3

Make sure that the correct version of Maven is installed (3.2.5+) and that the correct version of the JDK is installed (1.8+ or IBM SDK 7.1 if on IBM WebSphere). If you have multiple JDKs installed double check that Maven is using the correct version of the JDK. If you do not see this kind of output, and your operating system cannot find the mvn command, make sure that your PATH environment variable and M2_HOME environment variable have been properly set. You are now ready to start using the Alfresco SDK. Related Links Installing and configuring software on page 23

Creating a project The following tutorials take you step by step through how to create and run projects using the standard archetypes provided by the Alfresco SDK. The tutorials show creation of projects using: 1. Alfresco Repository AMP archetype - is this artifact for your project, read more here. 2. Alfresco Share AMP archetype - is this artifact for your project, read more here. 3. All-in-One archetype - is this artifact for your project, read more here. Related Links Getting Started with the Alfresco SDK on page 23 Creating a Repository extension project (AMP) on page 30 Creating a Share extension project (AMP) on page 34 Creating an All-in-One (AIO) project (WARs) on page 38

Creating a Repository extension project (AMP) The Alfresco Repository AMP maven archetype can be used to create a new Alfresco Module extension project for the alfresco.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 Alfresco SDK to generate a repository extension module containing a simple example web script. 1. Create a suitable directory in which to store all your Maven projects (if you have not already done so), such as alfresco-extensions. 2. Change into your alfresco-extensions directory. 3. Run the following command: mvn archetype:generate -Dfilter=org.alfresco:

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:

30 Alfresco 5.1

Developer Guide

1: remote -> org.alfresco.maven.archetype:alfresco-allinone-archetype (Sample multi-module project for All-in-One development on the Alfresco 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 (Alfresco Module Packages)) 3: remote -> org.alfresco.maven.archetype:share-amp-archetype (Share project with full support for lifecycle and rapid development of AMPs (Alfresco Module Packages)) Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): :

4. Enter 2 to have Maven generate an Alfresco Repository Module Package (AMP) project. 5. 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 8: 2.2.0 Choose a number: 8:

Press Enter to select the default (the most recent version). 6. 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. 7. 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 Alfresco Repository. Try and name the Repository extensions in a way so it is easy to see what kind of extension it is for the alfresco.war application. Here are some example names for repo extensions so you get the idea: zip-and-downloadaction-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 an Alfresco Repository extension. Note, hyphens are typically used in artifact IDs. 8. 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. Java packages cannot have hyphens in them. 9. 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.

Developer Guide 31

Developer Guide

A new project directory containing a number of sub-directories and support files for the AMP will be created in the directory componentX-repo. 10.

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 Alfresco WAR and run in Tomcat) ### run.bat (Windows script to have this AMP applied to the Alfresco WAR and run in Tomcat) ### src # ### main # # ### amp (For more information about the AMP structure see: http://docs.alfresco.com/community/concepts/dev-extensions-modulesintro.html) # # # ### config # # # # ### alfresco # # # # ### 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) # # # # ### alfresco-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) # # # # # ### webscript-context.xml (Your Web Script Java controller beans) # # # # ### 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 Alfresco) # # # ### module.properties (AMP module ID, Version etc) # # # ### web (If your AMP has some UI the files would go here, unlikely now when the Alfresco 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 and demo web script controller, can be removed)

32 Alfresco 5.1

Developer Guide

# # # # # # # # # #

# ### DemoComponent.java # ### Demo.java # ### HelloWorldWebScript.java ### test ### java # ### com # ### acme # ### componentX # ### demoamp # ### test (Example test of the demo component, can be removed) # # ### DemoComponentTest.java # ### properties # # ### local # # ### alfresco-global.properties (environment specific configuration, the local env is active by default) # ### resources # ### alfresco # # ### 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)

11.

At this point, before you have made any changes, you can build the project by typing: mvn install

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.0SNAPSHOT/componentX-repo-1.0-SNAPSHOT.amp

12.

Run and Test the sample Web Script To test the Web Script you will need to start an embedded Tomcat and deploy the Alfresco 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. This will only run the customized Alfresco Repository application (alfresco.war), Alfresco 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 INFO: WSSERVLET14: JAX-WS servlet initializing 2015-04-30 10:04:39,152 WARN [shared_impl.util.LocaleUtils] [localhoststartStop-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]

Developer Guide 33

Developer Guide

2015-04-30 10:05:24,741 INFO [management.subsystems.ChildApplicationContextFactory] [SearchScheduler_Worker-1] Startup of 'Transformers' subsystem, ID: [Transformers, default] complete

You may first need to make the shell script executable using the command chmod +x run.sh. 13.

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 from JS! HelloFromJava

14.

If you are prompted to login, then use username admin and a password admin.

15.

Configure Enterprise Edition (Optional) So far we have used the project with its default configuration, which is using Alfresco Community Edition 5.1.e. 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.1.0 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 5.1.e 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.1.0 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 # # # # ### alfresco # # # # ### extension # # # # # ### license # # # # # ### acme-5.1.0-enterprise.lic

In this tutorial you have learned how to generate, deploy, and run a project using the Repository AMP archetype. Related Links Creating a project on page 30

Creating a Share extension project (AMP) The Alfresco Share AMP maven archetype can be used to create a new Alfresco Module extension project for the share.war.For more information about this project type see Share AMP Archetype This task assumes you have completed all instructions in Installing and configuring software.

34 Alfresco 5.1

Developer Guide

This task shows how you can use the Share AMP archetype of the Alfresco SDK to generate a Share webapp extension module containing a simple Aikau Page and Widget (Aikau is the new Alfresco UI Framework used to build web pages and Dashlets). 1. Create a suitable directory in which to store all your Maven projects (if you have not already done so), such as alfresco-extensions. 2. Change into your alfresco-extensions directory. 3. Run the following command: mvn archetype:generate -Dfilter=org.alfresco:

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 Alfresco 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 (Alfresco Module Packages)) 3: remote -> org.alfresco.maven.archetype:share-amp-archetype (Share project with full support for lifecycle and rapid development of AMPs (Alfresco Module Packages)) Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): :

4. Enter 3 to have Maven generate an Alfresco Share Module Package (AMP) project. 5. 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 8: 2.2.0 Choose a number: 8:

Press Enter to select the default (which is the most recent version). 6. 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. 7. You will then be prompted to enter a value for the property artifactId: Define value for property 'artifactId': : componentX-share

Here we have specified componentX-share representing an X component with a specific extension for the Alfersco Share UI. Try and name the Share extensions in a way so it is easy to see what kind of extension it is for the share.war application. Here are some example names for share extensions so you get the idea: zip-and-download-action-share, digital-signature-share, business-reporting-share, these share extensions would typically have corresponding Repo extensions if they also include server side business logic as part of the implementation. It is good practice to use the following naming convention for

Developer Guide 35

Developer Guide

share extensions: {name}-share, where -share indicates that this is an Alfresco Share extension. Note, hyphens are typically used in artifact IDs. 8. 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. Java packages cannot have hyphens in them. 9. 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-share. 10.

Change into the freshly created componentX-share directory and browse the various files and directories to see what has been created. The following directory structure has been created for you: componentX-share/ ### pom.xml (Maven project file) ### run.sh (Mac/Linux script to have this AMP applied to the Share WAR and run in Tomcat) ### run.bat (Windows script to have this AMP applied to the Share WAR and run in Tomcat) ### src # ### main # # ### amp (For more information about the AMP structure see: https://wiki.alfresco.com/wiki/AMP_Files) # # # ### config # # # # ### alfresco # # # # ### web-extension # # # # ### componentX-share-slingshot-applicationcontext.xml (Loads componentX-share.properties) # # # # ### messages # # # # # ### componentX-share.properties (Custom share UI labels, messages etc) # # # # ### site-data # # # # # ### extensions # # # # # ### componentX-share-example-widgets.xml (Dojo package definitions for the Aikau framework, Share config) # # # # ### site-webscripts # # # # ### com # # # # # ### example # # # # # ### pages # # # # # ### simple-page.get.desc.xml (Simple Aikau page for demonstration purpose) # # # # # ### simple-page.get.html.ftl # # # # # ### simple-page.get.js # # # # ### org # # # # ### alfresco # # # # ### README.md # # # ### file-mapping.properties # # # ### module.properties # # # ### web # # # ### js # # # ### example # # # ### widgets (Simple Aikau widget for demonstration purpose) # # # ### css

36 Alfresco 5.1

Developer Guide

# # # # # # # # # # # # # # #

# # ### TemplateWidget.css # ### i18n # # ### TemplateWidget.properties # ### templates # # ### TemplateWidget.html # ### TemplateWidget.js ### java # ### com # ### acme # ### componentX ### resources ### META-INF ### resources # ### test.html ### share-config-custom.xml.sample (Remove .sample to use and keep extension specific stuff in this config) # ### test # ### java # # ### com # # ### acme # # ### componentX # ### properties # ### resources # ### alfresco # # ### web-extension # # ### share-config-custom.xml (Configures where the Repository is running) # ### log4j.properties ### tomcat ### context.xml (Virtual Webapp context for RAD development)

11.

# # # # # # # # # # # # # # #

At this point, before you have made any changes, you can build the project by typing: mvn install

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-share/1.0SNAPSHOT/componentX-share-1.0-SNAPSHOT.amp

12.

Run and Test the sample Aikau Page For this to work you will need to have the Alfresco WAR running in another Tomcat (8080). You can quite easily achieve this by generating a repo-amp project and running it, see Repository AMP Project. To test the custom Share page you will need to start an embedded Tomcat (8081) and deploy the Share WAR with the componentX-share 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.

Let's start Tomcat via the script as follows (use run.bat on Windows): ./run.sh ... Apr 30, 2015 11:40:42 AM org.apache.catalina.core.ApplicationContext log INFO: org.tuckey.web.filters.urlrewrite.UrlRewriteFilter INFO: loaded (conf ok) Apr 30, 2015 11:40:42 AM org.apache.catalina.core.ApplicationContext log INFO: Initializing Spring FrameworkServlet 'Spring Surf Dispatcher Servlet' Apr 30, 2015 11:40:42 AM org.apache.coyote.AbstractProtocol start

Developer Guide 37

Developer Guide

INFO: Starting ProtocolHandler ["http-bio-8081"]

You may first need to make the shell script executable using the command chmod +x run.sh. 13.

Once the web application has started (it may take a little while), point your browser at http://localhost:8081/share/page/hdp/ws/simple-page to test the sample Page. The page should return the following Title: This is a simple page and a Hello World widget with the text: Hello from i18n!

14.

If you are prompted to login, then use username admin and a password admin.

15.

Configure Enterprise Edition (Optional) So far we have used the project with its default configuration, which is using Alfresco Community Edition 5.1.e. If you are going to work with the Enterprise edition then you need to do the following: • Decide what Enterprise version you will be using, if you are going to use version 5.1.0 then you are set as that is the default Enterprise version. If you want to use another version then open up the componentX-share/pom.xml file and uncomment the 5.1.e property and set the new version number you want to use. • 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.1.0 if you have not explicitly set it. • 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

In this tutorial you have learned how to generate, deploy, and run a project using the Share AMP archetype. Related Links Creating a project on page 30

Creating an All-in-One (AIO) project (WARs) The All-in-One maven archetype can be used to create a new multi-module project that will produce customized alfresco.war and share.war artifacts. For more information about this project type see All-in-One Archetype This task assumes that you have completed all instructions in Installing and configuring. This task shows how you can use the All-in-One archetype of the Alfresco SDK to generate a multi module extension project containing repo-amp, share-amp, and WAR projects. 1. Create a suitable directory in which to store all your Maven projects (if you have not already done so), such as alfresco-extensions. 2. Change into your alfresco-extensions directory. 3. Run the following command: mvn archetype:generate -Dfilter=org.alfresco:

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:

38 Alfresco 5.1

Developer Guide

1: remote -> org.alfresco.maven.archetype:alfresco-allinone-archetype (Sample multi-module project for All-in-One development on the Alfresco 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 (Alfresco Module Packages)) 3: remote -> org.alfresco.maven.archetype:share-amp-archetype (Share project with full support for lifecycle and rapid development of AMPs (Alfresco Module Packages)) Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): :

4. Enter 1 to have Maven generate an Alfresco All-in-One project. 5. 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 8: 2.2.0 Choose a number: 8:

Press Enter to select the default (which is the most recent version). 6. 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. 7. You will then be prompted to enter a value for the property artifactId: Define value for property 'artifactId': : acme-cms-poc

Here we have specified acme-cms-poc representing a Proof-of-Concept (PoC) Content Management System (CMS) project to validate Alfresco as a perfect fit. Try and name the All-in-One projects so it is easy to know what they contain/represent. The naming should represent complete projects in contrast to specific AMP extensions that just implements a specific functionality in a larger solution. Note, hyphens are typically used in artifact IDs. 8. You will then be prompted to enter a value for the property package: Define value for property 'package':

com.acme: : com.acme.cmspoc

Here we have specified com.acme.cmspoc representing the top Java package for this project. 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 projects. Any Spring beans generated by this archetype will use this package in the ID. Java packages cannot have hyphens in them. 9. 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 project will be created in the directory acme-cms-poc. 10.

Change into the freshly created acme-cms-poc directory and browse the various files and directories to see what has been created.

Developer Guide 39

Developer Guide

The following directory structure has been created for you: acme-cms-poc/ ### pom.xml (Maven project file) ### run.sh (Mac/Linux script to run customized Alfresc WAR and Share WAR together with Solr4 in Tomcat) ### run.bat (Windows script to run customized Alfresc WAR and Share WAR together with Solr4 in Tomcat) ### acme-cms-poc-repo-amp (This is a standard Repository AMP extions project - produces a Repository AMP) # ### pom.xml (Maven project file for AMP, put dependencies here that are only needed by this AMP) # ### src # ### main # # ### amp (For more information about the AMP structure see: https://wiki.alfresco.com/wiki/AMP_Files) # # # ### config # # # # ### alfresco # # # # ### 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 # # # # ### acme-cms-poc-repo-amp (AMP Module ID) # # # # ### alfresco-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) # # # # # ### webscript-context.xml (Web Script Java controller beans) # # # # ### 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 Alfresco) # # # ### module.properties (AMP module ID, Version etc) # # # ### web (If your AMP has some UI the files would go here, unlikely now when the Alfresco 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 # # ### cmspoc # # ### demoamp (Demo module component and Web Script Java controller, can be removed) # # ### DemoComponent.java # # ### Demo.java # # ### HelloWorldWebScript.java # ### test

40 Alfresco 5.1

Developer Guide

# # # # # #

### java # ### com # ### acme # ### cmspoc # ### demoamp # ### test (Example test of the demo component, can be removed) # # ### DemoComponentTest.java # ### properties # # ### local # # ### alfresco-global.properties (environment specific configuration, the local env is active by default) # ### resources # ### alfresco # # ### extension # # ### disable-webscript-caching-context.xml (file to disable server side JavaScript compilation to Java code) # ### test-log4j.properties ### acme-cms-poc-share-amp (This is a standard Share AMP extions project - produces a Share AMP) # ### pom.xml (Maven project file for AMP, put dependencies here that are only needed by this AMP) # ### src # ### main # # ### amp (For more information about the AMP structure see: https://wiki.alfresco.com/wiki/AMP_Files) # # # ### config # # # # ### alfresco # # # # ### web-extension # # # # ### acme-cms-poc-share-amp-slingshotapplication-context.xml (Loads the acme-cms-poc-share-amp.properties file) # # # # ### messages # # # # # ### acme-cms-poc-share-amp.properties (Custom share UI labels, messages etc) # # # # ### site-data # # # # # ### extensions # # # # # ### acme-cms-poc-share-amp-examplewidgets.xml (Dojo package definitions for the Aikau framework, Share config) # # # # ### site-webscripts # # # # ### com # # # # # ### example # # # # # ### pages # # # # # ### simple-page.get.desc.xml (Simple Aikau page for demonstration purpose) # # # # # ### simple-page.get.html.ftl # # # # # ### simple-page.get.js # # # # ### org # # # # ### alfresco # # # # ### README.md # # # ### file-mapping.properties # # # ### module.properties # # # ### web # # # ### js # # # ### example # # # ### widgets (Simple Aikau widget for demonstration purpose) # # # ### css # # # # ### TemplateWidget.css # # # ### i18n # # # # ### TemplateWidget.properties # # # ### templates # # # # ### TemplateWidget.html # # # ### TemplateWidget.js # # ### java # # # ### com # # # ### acme

Developer Guide 41

Developer Guide

# # # # # # # # # #

# # ### cmspoc # ### resources # ### META-INF # ### share-config-custom.xml.sample ### test ### java # ### com # ### acme # ### cmspoc # ### demoamp (Example of how to use Alfresco Share Page Objects (PO) to create functional tests for your UI customizations) # # ### DemoPageTestIT.java # # ### po # # ### DemoPage.java # ### resources # ### testng.xml ### repo (This is the Alfresco WAR project - produces a customized Alfresco.WAR by applying the AMP produced by the /acme-cms-poc-repo-amp project) # ### pom.xml (Maven project file for Repository WAR (alfresco.war), add AMP and JAR dependencies and overlay config here) # ### src # ### main # ### properties # # ### local # # ### alfresco-global.properties # ### resources # ### alfresco # ### extension # ### dev-log4j.properties ### runner (Tomcat Runner that deploys the WARs produced by the /repo and /share projects, the Solr4 webapp is deployed directly from maven repo) # ### pom.xml # ### src # # ### main # # ### webapp # # ### index.html # ### tomcat (Virtual Webapp contexts for RAD development) # ### context-repo.xml # ### context-share.xml # ### context-solr.xml ### share (This is the Share WAR project - produces a customized Share.WAR by applying the AMP produced by the /acme-cms-poc-share-amp project) # ### pom.xml (Maven project file for Share WAR (share.war), add AMP and JAR dependencies and overlay config here) # ### src # ### main # # ### resources # # ### alfresco # # # ### web-extension # # # ### custom-slingshot-applicationcontext.xml.sample # # # ### share-config-custom.xml.sample # # ### log4j.properties # ### test # ### resources # ### alfresco # # ### web-extension # # ### share-config-custom.xml # ### log4j.properties ### solr-config (Loads the configuration files necessary for running Apache Solr4) ### pom.xml

42 Alfresco 5.1

Developer Guide

11.

At this point, before you have made any changes, you can build the project by typing: mvn install

Maven will ensure that all requirements are downloaded. This make take some time. As the build continues you will see the following artifacts built and installed in your local repository: • .m2/repository/com/acme/acme-cms-poc-repo-amp/1.0-SNAPSHOT/acme-cmspoc-repo-amp-1.0-SNAPSHOT.amp

• .m2/repository/com/acme/acme-cms-poc-share-amp/1.0-SNAPSHOT/acmecms-poc-share-amp-1.0-SNAPSHOT.amp

• .m2/repository/com/acme/repo/1.0-SNAPSHOT/repo-1.0-SNAPSHOT.war, contains the acme-cms-poc-repo-amp-1.0-SNAPSHOT.amp • .m2/repository/com/acme/share/1.0-SNAPSHOT/share-1.0-SNAPSHOT.war, contains the acme-cms-poc-share-amp-1.0-SNAPSHOT.amp The project will return with the message BUILD SUCCESS. 12.

You can build, load RAD requirements, and run your project by typing: ./run.sh

You may first need to make the shell script executable using the command chmod +x run.sh. 13.

Direct your web browser to: http://localhost:8080/share

You can log in using a user name of admin and a password of admin. 14.

Configure Enterprise Edition (Optional) So far we have used the project with its default configuration, which is using Alfresco Community Edition 5.1.e. 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.1.0 then you are set as that is the default Enterprise version. If you want to use another version then open up the acme-cms-poc/pom.xml file and uncomment the 5.1.e 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 -Prun,enterprise. Note. this automatically sets the version to 5.1.0 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 -Prun,enterprise

4.

Install an enterprise license, otherwise the server will be in read-only mode. It goes into the following directory: acme-cms-poc/ ### repo # ### pom.xml # ### src # ### main # ### properties # ### resources # ### alfresco

Developer Guide 43

Developer Guide

# # #

# #

# #

# #

### extension # ### license # ### acme-5.1.0-enterprise.lic

If the license is properly installed you should see logs as follows when the server starts: ... 2015-05-08 09:52:21,359 INFO [enterprise.license.AlfrescoLicenseManager] [localhost-startStop-1] Successfully installed license from file [/home/martin/src/alfrescoextensions/acme-cms-poc/runner/target/tomcat/webapps/repo/WEB-INF/ classes/alfresco/extension/license/Enterprise-5.0.lic] ... 2015-05-08 09:52:23,614 INFO [service.descriptor.DescriptorService] [localhost-startStop-1] Alfresco started (Enterprise). Current version: 5.0.1 (r100823-b68) schema 8,022. Originally installed version: 5.0.0 (d r99759-b2) schema 8,022. ...

In this tutorial you have learned how to generate, deploy, and run a project using the All-in-One (AIO) archetype. Related Links Creating a project on page 30

Maven Archetypes - Command Reference There are three Maven archetypes on which the Alfresco SDK can base the generation of projects. This information provides the Maven command reference for these projects. For more information about the archetypes see: • Repository AMP archetype • All-In-One (AIO) archetype • Share AMP archetype Related Links Alfresco SDK 2.2.0 on page 16 Repository AMP archetype command reference on page 44 Share AMP archetype command reference on page 46 All-in-One (AIO) archetype command reference on page 47

Repository AMP archetype command reference This describes the scripts and Maven commands that can be used on an Alfresco Repository extension project based on the Repository AMP archetype. Scripts and commands:

44 Alfresco 5.1

Developer Guide

Command

Description

./run.sh and run.bat

Linux/Mac and Windows scripts for running an embedded Tomcat with the customized alfresco.war (that is, with the Repo AMP applied) and the flat file database H2. Access to Alfresco UI is via http://localhost:8080/ alfresco. The username/password is admin/ admin. This script will also configure JVM memory (it basically sets up MAVEN_OPTS for you). See inside the script for further details. Note. Spring loaded is no longer used. This script assumes that you are developing for Alfresco Community Edition. If you use an Enterprise Edition you need to update the maven command in this script so it uses the enterprise profile: mvn integration-test -Pamp-towar,enterprise.

mvn compile alfresco:refresh-repo

Compiles the source code and puts the class files and resources under /target. Then makes a POST call to the Alfresco Repository web application (alfresco.war) to refresh the web script container. So any changes that were made to web scripts should be visible after a page refresh. This command is typically used together with the run.sh/bat script for Rapid Application Development (RAD). The RAD process can be described like this: 1.

Start Tomcat with current alfresco.war customization (run.sh/bat) in console window one.

2.

From an editor, change some files (classes, web scripts, and so on).

3.

Execute this cmd (mvn compile alfresco:refresh-repo) from console window two.

4.

Refresh the page/web script that you are working on.

5.

Done? No -> Go back to step 2 and start over.

6.

Finished with implementation.

mvn package

Runs unit tests and packages AMP in ${project.build.directory}/ ${project.build.finalName}.amp.

mvn install

Like mvn package but also installs AMP in local Maven repository to be depended upon.

mvn test

Runs unit tests.

mvn install -DskipTests=true

Like mvn install but skips unit tests.

mvn install -Pamp-to-war

Like run.sh or run.bat but does not configure JVM memory if you have not configured it in MAVEN_OPTS. See set up MAVEN_OPTS. If you use the Enterprise edition see the next command.

Developer Guide 45

Developer Guide

Command

Description

mvn install -Pamp-to-war,enterprise

Like mvn install -Pamp-to-war but uses Enterprise artifacts. Note you need to have set up access to the private repository containing the Enterprise artifacts.

mvn clean -Ppurge

Removes H2 database (with metadata), alf_data (with content files and index files), and log files. Useful to purge the development repo (by default self contained in ${project.basedir}/ alf_data_dev). This is an important command to use if you change significant settings in your project. For example, if you change Alfresco Community Edition to Enterprise. It is important to purge databases and other data that might otherwise be persisted. The purge profile cannot be used together with the amp-to-war profile.

Related Links Maven Archetypes - Command Reference on page 44

Share AMP archetype command reference This describes the scripts and Maven commands that can be used on an Alfresco Share extension project based on the Share AMP archetype. Scripts and commands: Command

Description

./run.sh and run.bat

Linux/Mac and Windows scripts for running an embedded Tomcat with the customized share.war (that is, with the Share AMP applied). Access to Alfresco Share UI is via http:// localhost:8081/share. The username/ password is admin/admin. This script will also configure JVM memory and automatically set up Spring Loaded for hot reloading of classes (it basically sets up MAVEN_OPTS for you). See inside script for further details. This script assumes that you are developing for the Alfresco Community Edition. If you use an Enterprise Edition you need to update the maven command in this script so it uses the enterprise profile: mvn integration-test -Pamp-towar,enterprise. This script also assumes that another Tomcat is running locally on port 8080 with the Alfresco Repository (alfresco.war) web application deployed.

46 Alfresco 5.1

Developer Guide

Command

Description

mvn compile alfresco:refresh-share

Compiles the source code and puts the class files and resources under /target. Then makes POST calls to the Alfresco Share web application (share.war) to refresh the Spring Surf web script container and clear dependency caches. So any changes that was made to web scripts, Aikau pages, Aikau Widgets, Dashlets, and so on, should be visible after a page refresh. This command is typically used together with the run.sh/bat script for Rapid Application Development (RAD). The RAD process can be described like this: 1.

Start Tomcat with current share.war customization (run.sh/bat) in console window one.

2.

From an editor change some files (classes, pages, widgets, and so on)

3.

Execute this cmd (mvn compile alfresco:refresh-share) from console window two.

4.

Refresh the page/web script you are working on.

5.

Done? No -> Go back to step 2 and start over.

6.

Finished with implementation.

mvn package

Runs unit tests and packages AMP in ${project.build.directory}/ ${project.build.finalName}.amp.

mvn install

Like mvn package but also installs AMP in local Maven repository to be depended upon.

mvn test

Runs unit tests.

mvn install -DskipTests=true

Like mvn install but skips unit tests.

mvn install -Pamp-to-war

Like run.sh or run.bat but does not configure JVM memory and Spring Loaded if you have not configured it in MAVEN_OPTS. See set up MAVEN_OPTS. If you use the Enterprise edition see next command.

mvn install -Pamp-to-war,enterprise

Like mvn install -Pamp-to-war but uses Enterprise artifacts. Note you need to have set up access to the private repository containing the Enterprise artifacts.

Related Links Maven Archetypes - Command Reference on page 44

All-in-One (AIO) archetype command reference This describes the scripts and Maven commands that can be used on an Alfresco All-in-One (AIO) extension project based on the AIO archetype.

Developer Guide 47

Developer Guide

The All-in-One Alfresco project contains the following modules: • repo-amp: A Repository AMP project, demonstrating sample project structure and demo component loading. • repo: An alfresco.war aggregator project, overlaying the standard Alfresco WAR with the repo-amp and any other AMPs and JARs that have been included as dependencies and configured in the overlay • share-amp: A Share AMP project, demonstrating sample project structure and demo Aikau page • share: A share.war aggregator project, overlaying the standard Share WAR with the share-amp and any other AMPs and JARs that have been included as dependencies and configured in the overlay • solr-config: Brings in the Apache Solr4 configuration files • runner: A Tomcat + H2 runner, capable of running the custom alfresco.war, custom share.war, and solr4.war in embedded mode for demo/integration-testing purposes Scripts and commands: Command

Description

./run.sh and run.bat

Linux/Mac and Windows scripts for running an embedded Tomcat with the customized alfresco.war (repo-amp applied), custom share.war (share-amp applied), and solr4.war. Access to Alfresco Share UI is via http:// localhost:8080/share. Username/pwd is admin/admin. This script will also configure JVM memory (it basically sets up MAVEN_OPTS for you). See inside script for further details. Note. Spring loaded is no longer used. This script assumes that you are developing for the Alfresco Community Edition. If you use Enterprise, you need to update the maven command in this script so it uses the 'enterprise' profile: mvn install -Prun,enterprise.

48 Alfresco 5.1

Developer Guide

Command

Description

repo-amp/mvn compile alfresco:refresh- Compiles the source code for the Repository repo AMP and puts the class files and resources under repo-amp/target. Then makes a POST call to the Alfresco Repository web application (alfresco.war) to refresh the web script container. So any changes that was made to Web scripts should be visible after a page refresh. This command is typically used together with the run.sh/bat script for Rapid Application Development (RAD). The RAD process can be described like this:

share-amp/mvn compile alfresco:refresh-share

1.

Start Tomcat with current alfresco.war customization (that is, run.sh/bat) in console window one.

2.

From an editor change some files (classes, web scripts, and so on) for the Repository AMP.

3.

Execute this cmd (that is, mvn repoamp/compile alfresco:refreshrepo) from console window two.

4.

Refresh the page / web script you are working on.

5.

Done? No -> Go back to step 2 and start over.

6.

Finished with implementation.

Compiles the source code for the Share AMP and puts the class files and resources under shareamp/target. Then makes POST calls to the Alfresco Share web application (share.war) to refresh the Spring Surf web script container and clear dependency caches. So any changes that was made to web scripts, Aikau pages, Aikau widgets, dashlets, and so on, should be visible after a page refresh. This command is typically used together with the run.sh/bat script for Rapid Application Development (RAD). The RAD process can be described like this: 1.

Start Tomcat with current share.war customization (that is, run.sh/bat) in console window one.

2.

From an editor change some files (classes, pages, widgets, and so on) for the Share AMP.

3.

Execute this cmd (that is, share-amp/ mvn compile alfresco:refreshshare) from console window two.

4.

Refresh the page / web script you are working on.

5.

Done? No -> Go back to step 2 and start over.

6.

Finished with implementation.

Developer Guide 49

Developer Guide

Command

Description

mvn package

Runs unit tests and packages modules in their respective target directories, for example: •

all-in-one/repo-amp/target/1.0SNAPSHOT/repo-amp-1.0SNAPSHOT.amp

•

all-in-one/share-amp/target/1.0SNAPSHOT/share-amp-1.0SNAPSHOT.amp

•

all-in-one/repo/target/1.0SNAPSHOT/repo-1.0-SNAPSHOT.war, contains repo-amp-1.0-SNAPSHOT.amp from local maven repo (not the just packed version)

•

all-in-one/share/target/1.0SNAPSHOT/share-1.0-SNAPSHOT.war, contains share-amp-1.0-SNAPSHOT.amp from local maven repo (not the just packed version)

This does not apply these newly packaged AMPs to their respective WARs, use mvn install for that. mvn install

Like mvn package but also installs artifacts in local Maven repository, for example: •

.m2/repository/com/acme/repoamp/1.0-SNAPSHOT/repo-amp-1.0SNAPSHOT.amp

•

.m2/repository/com/acme/shareamp/1.0-SNAPSHOT/share-amp-1.0SNAPSHOT.amp

•

.m2/repository/com/acme/repo/1.0SNAPSHOT/repo-1.0-SNAPSHOT.war, contains the repo-amp-1.0-SNAPSHOT.amp

•

.m2/repository/com/acme/ share/1.0-SNAPSHOT/share-1.0SNAPSHOT.war, contains the shareamp-1.0-SNAPSHOT.amp

Where these artifacts can be accessed by other local projects that depend on them. mvn install -DskipTests=true

Like mvn install but skips unit tests.

mvn install -Prun

Like run.sh or run.bat but does not configure JVM memory and Spring Loaded if you have not configured it in MAVEN_OPTS, see set up MAVEN_OPTS. If you use the Enterprise edition, see the next command.

mvn install -Prun,enterprise

Like mvn install -Prun but uses Enterprise artifacts. Note you need to have set up access to the private repository containing the Enterprise artifacts.

50 Alfresco 5.1

Developer Guide

Command

Description

mvn clean install -Prun,regression-testing

Runs regression testing of the Alfresco Share UI (share.war). Uses the Alfresco internal Selenium Page Object (PO) based tests. This is very useful when you have developed a lot of customizations for the Share UI and you want to make sure you have not broken any standard Share UI functionality. Typically run this from a CI server (or better a Selenium-Grid) to test for regression of the standard Alfresco Share UI. The Selenium WebDriver is configured to use FireFox (FF) by default, so you need to have FF installed for the regression tests to be able to run. Use version 35 or newer. It is also highly recommended that the workstation that is running the regression tests is not being worked on at the same time as the tests are running, as that can affect the outcome of the tests. This command assumes that you are developing for the Alfresco Community Edition. If you use Enterprise, you need to update the maven command so it uses the 'enterprise' profile and the Enterprise share-po library: mvn clean install -Prun,enterprise,regressiontesting. Also, make sure that you have installed an enterprise license in the repo project, otherwise the system will be in read-only mode and loads of tests will not pass.

mvn clean install -Prun,functional-testing

Runs functional testing of the Alfresco Share UI customizations that you have developed, such as pages and Dashlets. For information about how to write these tests, see the example test called share-amp/src/test/java/{packagepath}/demoamp/DemoPageTestIT and its Page Object class called share-amp/src/ test/java/{package-path}/demoamp/po/ DemoPage.java. The Selenium WebDriver is configured to use FireFox (FF) by default, so you need to have FF installed for the functional tests to be able to run. Use version 35 or newer. It is also highly recommended that the workstation that is running the functional tests is not being worked on at the same time as the tests are running, as that can affect the outcome of the tests. This command assumes that you are developing for Alfresco Community Edition. If you use Enterprise, you need to update the maven command so it uses the 'enterprise' profile and the Enterprise share-po library: mvn clean install Prun,enterprise,functional-testing.

Developer Guide 51

Developer Guide

Command

Description

mvn clean -Ppurge

Removes H2 database (with metadata), alf_data (with content files and index files), and log files. Useful to purge the development repo (by default self contained in ${project.basedir}/ alf_data_dev. This is an important command to use if you change significant settings in your project. For example, if you change Alfresco from Community Edition to Enterprise. It is important to purge databases and other data that might otherwise be persisted. The purge profile cannot be used together with the run profile.

Related Links Maven Archetypes - Command Reference on page 44

Rapid Application Development (RAD) These tutorials cover how to employ the RAD features of the Alfresco SDK. Rapid Application Development (RAD) and Test Driven Development (TDD) are big goals for the Alfresco SDK. The SDK is designed to support the hot reloading of code (via Spring Loaded) so that you can modify JavaScript, FreeMarker and Java code, and have the changes take effect without having to click the Refresh Web Scripts button, restart Alfresco Tomcat, or restart anything else. For example, in your SDK project, you can change test code, re-run your test, and the results will be displayed immediately. This allows for Test Driven Development (TDD). The hot reloading above all saves you time as a developer. No more waiting around for Alfresco Tomcat restarts to see your code changes take effect. It is assumed that you will work through the tutorials in the order in which they are presented. Related Links Alfresco SDK 2.2.0 on page 16 Importing SDK projects into Eclipse on page 52 Rapid Application Development in Eclipse (Hot reloading) on page 56 Importing SDK projects into IntelliJ IDEA on page 66 Rapid Application Development in IntelliJ IDEA (Hot reloading) on page 71 Remote debugging with an IDE on page 85

Importing SDK projects into Eclipse The Alfresco SDK is designed to work well with Eclipse. This support includes the ability to import existing SDK projects (created via the command line) into Eclipse. You should have completed Installing and Configuring software and generated a project. You will learn how to import an existing Maven project into Eclipse. 1. In Eclipse, from the main menu select File > Import... > Maven > Existing Maven Projects . 2. Click Next > 3. Click Browse...>

52 Alfresco 5.1

Developer Guide

4. Navigate to the directory where your Maven project is located. For example alfrescoextensions/all-in-one. You should see a dialog looking something like this when importing an All-in-One (AIO) project:

5. Click Finish The project, and any sub-projects, will now be imported. 6. Enable Alfresco Enterprise edition (Optional) If your project is using the Enterprise edition of Alfresco you also want Eclipse to load the enterprise versions of the Alfresco WARs and related libraries. You can do this by enable

Developer Guide 53

Developer Guide

the enterprise profile. In the Package Explorer view to the left, right click on the allin-one project, then select Maven from the popup menu. Now in the next popup menu choose Select Maven Profiles.... In the dialog that appears select the enterprise profile, you should see a dialog looking something like this now:

7. Configure external Maven Use the external Maven installation. In the Window top menu to the right in Eclipse, click on the Preferences sub-menu item at the bottom, then select Maven from the pop-up dialog menu. Now in the Maven sub-menu choose Installations. In the dialog that appears to the right select the external Maven installation (or add it if it is not in the list), you should see a dialog looking something like this now:

54 Alfresco 5.1

Developer Guide

Now close this Preferences dialog and open the Run Configurations dialog. Make sure the external Maven configuration is used:

Developer Guide 55

Developer Guide

If the EMBEDDED Maven installation is used then you might encounter the EXCEPTION_ACCESS_VIOLATION JRE error when running. You have seen how to import your SDK project(s) into Eclipse. You can now build, run and debug them in the usual way, using RAD and TDD techniques. Related Links Rapid Application Development (RAD) on page 52

Rapid Application Development in Eclipse (Hot reloading) Hot reloading is the ability to modify your application's code, and view the changes without having to restart Alfresco Tomcat. This allows for significant savings in development time that would otherwise be wasted restarting Tomcat. Hot reloading is the key to enabling Rapid Application Development (RAD) and Test Driven Development (TDD). You should have an extension project imported, see importing a project into Eclipse. In this tutorial you will see how changes to your code can be carried out without having to restart Alfresco Tomcat. This tutorial demonstrates hot reloading of JavaScript, FreeMarker template, and Java code. There are three components that work together to enable the best RAD experience: 1. Spring Loaded: takes care of hot-reloading any Java class files that we have changed.

56 Alfresco 5.1

Developer Guide

2. Refresh Repository Script: This is a script that will POST a request to the Alfresco Repository Web Application (i.e. alfresco.war) telling it to refresh the Repo Web Script container, so any changes to files related to Web Scripts will be picked up. 3. Refresh Share Script: This is a script that will POST a request to the Alfresco Share Web Application (i.e. share.war) telling it to refresh the Surf Web Script container, so any changes to files related to Surf Web Scripts will be picked up. This script will also clear the resource dependency caches, so JS changes etc are picked up. Start an instance of Alfresco Tomcat that will be used for hot-reloading. 1. Use the run script to start the Application server with the Alfresco extension project deployed, for example:

alfresco-extensions/all-in-one$ ./run.sh

This is usually done outside the IDE. 2. Test the custom Repository Web Script The All-in-One project (and the Repository AMP project) have a sample Web Script included. You can invoke it by pointing your web browser at http://localhost:8080/ alfresco/service/sample/helloworld. If you need to login then use admin with password admin. Running this Web Script produces the output "Message: Hello World from JS! HelloFromJava". 3. Test the custom Share Aikau Page The All-in-One project (and the Share AMP project) have a sample Aikau page included. You can display it by pointing your web browser at http://localhost:8080/share/ page/hdp/ws/simple-page. If you need to login then use admin with password admin. The page should display as follows:

Enabling Rapid Application Development (RAD) in Eclipse. 4. This is enabled by default and there is no specific configuration needed. If you want to have more control over when web applications are refreshed, then see the last tutorial about Run Configurations. Testing RAD when doing Repository customizations (alfresco.war). 5. In the Package Explorer, navigate to and expand the all-in-one/repo-amp/src/main/ amp/config/alfresco/extension/templates/webscripts folder 6. Locate the helloworld.get.js file and load it into the editor by double-clicking it.

Developer Guide 57

Developer Guide

This is the controller for the Web Script that we tried after starting the server. Update the controller code by adding an 'UPDATED' string as follows: model["fromJS"] = "Hello World from JS! UPDATED";

7. Now build(Make) the project by saving, i.e. click Ctrl+S The application server log should display messages about the web scripts being refreshed: 2015-05-12 11:13:40,652 INFO [extensions.webscripts.DeclarativeRegistry] [http-bio-8080-exec-9] Registered 407 Web Scripts (+0 failed), 549 URLs 2015-05-12 11:13:40,653 INFO [extensions.webscripts.DeclarativeRegistry] [http-bio-8080-exec-9] Registered 1 Package Description Documents (+0 failed) 2015-05-12 11:13:40,653 INFO [extensions.webscripts.DeclarativeRegistry] [http-bio-8080-exec-9] Registered 0 Schema Description Documents (+0 failed) 2015-05-12 11:13:40,656 INFO [extensions.webscripts.AbstractRuntimeContainer] [http-bio-8080-exec-9] Initialised Repository Web Script Container (in 2215.1865ms) 2015-05-12 11:13:42,414 INFO [extensions.webscripts.DeclarativeRegistry] [asynchronouslyRefreshedCacheThreadPool1] Registered 407 Web Scripts (+0 failed), 549 URLs 2015-05-12 11:13:42,414 INFO [extensions.webscripts.DeclarativeRegistry] [asynchronouslyRefreshedCacheThreadPool1] Registered 1 Package Description Documents (+0 failed) 2015-05-12 11:13:42,414 INFO [extensions.webscripts.DeclarativeRegistry] [asynchronouslyRefreshedCacheThreadPool1] Registered 0 Schema Description Documents (+0 failed)

Note that there is no output in the Eclipse console, or other window. Also, it is only the Repository Application (i.e. alfresco.war) that is being refreshed, the Share application is not touched. 8. Refresh the http://localhost:8080/alfresco/service/sample/helloworld Repository Web Script page from the Browser The output from the Web Script should change to "Message: Hello World from JS! UPDATED HelloFromJava". Note that there is no need to restart the application server, just a Make of the project, and a refresh of the Web Script page from the browser (you are basically invoking the Web Script again and the update should be immediately visible). 9. Now locate the helloworld.get.html.ftl file and load it into the editor by doubleclicking it. This is the FreeMarker template for the Web Script. Update the template by adding an 'ExtraTemplateText' string as follows: Message: ${fromJS} ${fromJava} ExtraTemplateText

10.

Now build(Make) the project by clicking Ctrl+S The application server log should display messages about the web scripts being refreshed.

11.

Refresh the http://localhost:8080/alfresco/service/sample/helloworld Repository Web Script page from the Browser The output from the Web Script should change to "Message: Hello World from JS! UPDATED HelloFromJava ExtraTemplateText ". Again, note that there is no need to

58 Alfresco 5.1

Developer Guide

restart the application server, only a Make of the project and a refresh of the Web Script page are necessary. 12.

In the next demo we will add a properties file for the Web Script, create a helloworld.get.properties file next to the other files we have been working with. The properties file should have one property as follows: hello.word.extras=Extra Stuff From Props

13.

Add this property to the template, open up helloworld.get.html.ftl. The FreeMarker template should now look like this: Message: ${fromJS} ${fromJava} ${msg("hello.word.extras")}

14.

ExtraTemplateText

Now build(Make) the project by clicking Ctrl+S The application server log should display messages about the web scripts being refreshed.

15.

Refresh the http://localhost:8080/alfresco/service/sample/helloworld Repository Web Script page from the Browser The output of the Web Script should change to "Message: Hello World from JS! UPDATED HelloFromJava ExtraTemplateText Extra Stuff From Props". No restart of application server should be needed, just a Make of the project and a refresh of the Web Script page from the browser.

16.

In the last Web Script demo we will change the Java controller

17.

Open up all-in-one/repo-amp/src/main/java/{your package path}/demoamp/ HelloWorldWebScript.java. Change the property text as follows: public class HelloWorldWebScript extends DeclarativeWebScript { protected Map executeImpl( WebScriptRequest req, Status status, Cache cache) { Map model = new HashMap(); model.put("fromJava", "HelloFromJavaUPDATED"); return model; } }

18.

Now build(Make) the project by clicking Ctrl+S The application server log should display messages about the web scripts being refreshed.

19.

Refresh the http://localhost:8080/alfresco/service/sample/helloworld Repository Web Script page from the Browser The output of the Web Script should change to "Message: Hello World from JS! UPDATED HelloFromJavaUPDATED ExtraTemplateText Extra Stuff From Props". No restart of application server should be needed, just a Make of the project and a refresh of the Web Script page from the browser.

Test Driven Development (TDD) and RAD when doing Repository customizations (alfresco.war). 20.

In the Package Explorer expand all-in-one/repo-amp/src/test/java/{your package path}/demoamp/test and then locate the DemoComponentTest.java source file.

21.

Load it into the editor by double-clicking it.

22.

Now set up a Run Configuration to run repo-amp tests. From the main menu select Run > Run Configurations... .

Developer Guide 59

Developer Guide

23.

In the Run Configurations dialog, select Maven Build in the left list. Then right click on it and select New.

24.

Set the Name field of the configuration to "Test Repo AMP".

25.

Set the Base Directory field of the configuration to "${workspace_loc:/repo-amp}".

26.

Set the Goals field "test".

27.

In the JRE tab set JDK 8.

28.

Click Apply.

29.

Now run the test by selecting Run. The test will run, and three tests will pass, the Console will have logs as follows:

[INFO] Scanning for projects... [INFO] [INFO] -----------------------------------------------------------------------[INFO] Building Alfresco Repository AMP Module 1.0-SNAPSHOT [INFO] -----------------------------------------------------------------------[INFO] [INFO] --- alfresco-maven-plugin:2.1.0-SNAPSHOT:set-version (default-setversion) @ repo-amp --[INFO] Removed -SNAPSHOT suffix from version - 1.0 [INFO] Added timestamp to version - 1.0.1505121136 [INFO] [INFO] --- build-helper-maven-plugin:1.9.1:add-test-resource (add-envtest-properties) @ repo-amp --[INFO] [INFO] --- maven-resources-plugin:2.7:resources (default-resources) @ repo-amp --[INFO] Using 'UTF-8' encoding to copy filtered resources. [INFO] skip non existing resourceDirectory /home/martin/src/alfrescoextensions/all-in-one/repo-amp/src/main/resources [INFO] Copying 16 resources to ../repo-amp [INFO] [INFO] --- yuicompressor-maven-plugin:1.5.1:compress (compress-js) @ repo-amp --[INFO] nothing to do, /home/martin/src/alfresco-extensions/all-in-one/ repo-amp/target/classes/../repo-amp/web/scripts/demoamp-min.js is younger than original, use 'force' option or clean your target [INFO] nb warnings: 0, nb errors: 0 [INFO] [INFO] --- alfresco-maven-plugin:2.1.0-SNAPSHOT:refresh (refreshwebscripts-repo-and-share) @ repo-amp --[INFO] Successfull Refresh Web Scripts for Alfresco Repository [INFO] [INFO] --- maven-compiler-plugin:3.2:compile (default-compile) @ repo-amp --[INFO] Nothing to compile - all classes are up to date [INFO] [INFO] --- maven-resources-plugin:2.7:testResources (defaulttestResources) @ repo-amp --[INFO] Using 'UTF-8' encoding to copy filtered resources. [INFO] Copying 2 resources [INFO] Copying 1 resource [INFO] [INFO] --- maven-resources-plugin:2.7:copy-resources (add-moduleproperties-to-test-classpath) @ repo-amp --[INFO] Using 'UTF-8' encoding to copy filtered resources. [INFO] Copying 1 resource to alfresco/module/repo-amp [INFO]

60 Alfresco 5.1

Developer Guide

[INFO] --- maven-resources-plugin:2.7:copy-resources (add-module-configto-test-classpath) @ repo-amp --[INFO] Using 'UTF-8' encoding to copy filtered resources. [INFO] Copying 11 resources [INFO] [INFO] --- maven-compiler-plugin:3.2:testCompile (default-testCompile) @ repo-amp --[INFO] Nothing to compile - all classes are up to date [INFO] [INFO] --- maven-surefire-plugin:2.18:test (default-test) @ repo-amp --[INFO] Surefire report directory: /home/martin/src/alfresco-extensions/ all-in-one/repo-amp/target/surefire-reports ------------------------------------------------------T E S T S ------------------------------------------------------Running org.alfresco.allinone.demoamp.test.DemoComponentTest Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.088 sec - in org.alfresco.allinone.demoamp.test.DemoComponentTest Results : Tests run: 3, Failures: 0, Errors: 0, Skipped: 0 [INFO] -----------------------------------------------------------------------[INFO] BUILD SUCCESS [INFO] -----------------------------------------------------------------------[INFO] Total time: 7.232 s [INFO] Finished at: 2015-05-12T11:36:13+01:00 [INFO] Final Memory: 27M/338M [INFO] ------------------------------------------------------------------------

30.

Now, in DemoComponentTest.java, modify one of the tests so that it will fail. For example, you could change the line assertEquals(7, childNodeCount); to assertEquals(8, childNodeCount);

31.

Now run the test again by selecting Run from main menu and then from Run History select Run 'Test Repo AMP'. Note the test will run again and this time fail. But you did not need to restart Alfresco. This demonstrates hot reloading of Java code.

32.

Change the code back and re-run the test. Now you will see that all tests pass. The code has re-run without any reloading of Alfresco! This allows for Test Driven Development with very low overhead.

Testing RAD when doing Share customizations (share.war). 33.

In the Package Explorer, navigate to and expand the all-in-one/share-amp/src/main/ amp/config/alfresco/web-extension/site-webscripts/com/example/pages folder

34.

Locate the simple-page.get.js file and load it into the editor by double-clicking it. This is the controller for the Aikau Page Web Script that we tried after starting the server. Update the controller code by adding an 'UPDATED' string as follows to the page title, also change the layout from HorizontalWidgets to VerticalWidgets: model.jsonModel = { widgets: [{ id: "SET_PAGE_TITLE", name: "alfresco/header/SetTitle", config: {

Developer Guide 61

Developer Guide

title: "This is a simple page UPDATED" } }, { id: "MY_HORIZONTAL_WIDGET_LAYOUT", name: "alfresco/layout/VerticalWidgets", config: { widgetWidth: 50, widgets: [ { id: "DEMO_SIMPLE_LOGO", name: "alfresco/logo/Logo", config: { logoClasses: "alfresco-logo-only" } }, { id: "DEMO_SIMPLE_MSG", name: "example/widgets/TemplateWidget" } ] } }] };

35.

Now build(Make) the project by clicking Ctrl+S The Share web application will now have the web script container refreshed and the resouce cache cleared.

36.

Refresh the http://localhost:8080/share/page/hdp/ws/simple-page Aikau Page from the Browser The page should now display as follows:

37.

Now, let's update some HTML, CSS, and Properties for the sample widget that is used by the Aikau page, navigate to and expand the all-in-one/share-amp/src/main/amp/ web/js/example/widgets folder

38.

Locate the css/TemplateWidget.css file and load it into the editor by double-clicking it.

62 Alfresco 5.1

Developer Guide

This is the Stylesheet for the Aikau Widget. Update the widget style as follows: .my-template-widget { border: 2px #000000 solid; padding: 1em; width: 100px; color: white; background-color: blue; }

39.

Then locate the i18n/TemplateWidget.properties file and load it into the editor by double-clicking it. This is the resource file for the Aikau Widget. Update the properties as follows: hello-label=Hello from i18n UPDATED! hello-test=Going to use this label too now!

40.

Then locate the templates/TemplateWidget.html file and load it into the editor by double-clicking it. This is the HTML template file for the Aikau Widget. Update so it looks as follows: ${greeting} and ${greeting2}

41.

And finally, locate the TemplateWidget.js file and load it into the editor by double-clicking it. This is the main JavaScript implementation for the Aikau Widget. Update so it also sets the new property used in template: define(["dojo/_base/declare", "dijit/_WidgetBase", "alfresco/core/Core", "dijit/_TemplatedMixin", "dojo/text!./templates/TemplateWidget.html" ], function(declare, _Widget, Core, _Templated, template) { return declare([_Widget, Core, _Templated], { templateString: template, i18nRequirements: [ {i18nFile: "./i18n/ TemplateWidget.properties"} ], cssRequirements: [{cssFile:"./css/TemplateWidget.css"}], buildRendering: function example_widgets_TemplateWidget__buildRendering() { this.greeting = this.message('hello-label'); this.greeting2 = this.message('hello-test'); this.inherited(arguments); } }); });

42.

Now build(Make) the project by clicking Ctrl+S.

43.

Refresh the http://localhost:8080/share/page/hdp/ws/simple-page Aikau Page from the Browser. The page should now display as follows:

Developer Guide 63

Developer Guide

Enabling RAD in Eclipse with Run Configurations. 44.

Introduction In this article we have seen how we can achieve Rapid Application Development within Eclipse by having the alfresco maven plugin refresh goals executed automatically (magically) after a Make, which is triggered by saving the file. This auto-refresh feature is enabled by default when you use Eclipse. If you don't want that, and instead want to have more control over when web application refreshs happens etc, then you can use a Run Configuration instead and disable auto-refresh. In the following tutorial you will see how run configurations can be used for better control of when the refresh call is being made.

45.

Start by disabling auto-refresh, set the following property in the top project POM (i.e. in alfresco-extensions/all-in-one/pom.xml):

... http://localhost:8080/share none

Besides none, the other values for this property are: • auto - (default) Checks packaging and app.amp.client.war.artifactId to determine if it should refresh Respository (alfresco.war) or Share (share.war) • both - Will refresh both Respository and Share • share - Refresh only Share • repo - Refresh only Respository • none - Disables refreshing all together

64 Alfresco 5.1

Developer Guide

46.

Then set up a Run Configuration to run repo-amp builds and Repository webapp refresh (alfresco.war). From the main menu select Run > Run Configurations... .

47.

In the Run Configurations dialog, select Maven Build in the left list. Then right click on it and select New.

48.

Set the Name field of the configuration to "Make Repo AMP".

49.

Set the Base Directory field of the configuration to "${workspace_loc:/repo-amp}".

50.

Set the Goals field "compile alfresco:refresh-repo".

51.

In the JRE tab set JDK 8.

52.

Click Apply.

53.

Now run the repo-amp build by selecting Run. The build will run with the following result, the Eclipse Console will output:

[INFO] Scanning for projects... [INFO] [INFO] -----------------------------------------------------------------------[INFO] Building Alfresco Repository AMP Module 1.0-SNAPSHOT [INFO] -----------------------------------------------------------------------[INFO] [INFO] --- alfresco-maven-plugin:2.1.0-SNAPSHOT:set-version (default-setversion) @ repo-amp --[INFO] Removed -SNAPSHOT suffix from version - 1.0 [INFO] Added timestamp to version - 1.0.1505121201 [INFO] [INFO] --- build-helper-maven-plugin:1.9.1:add-test-resource (add-envtest-properties) @ repo-amp --[INFO] [INFO] --- maven-resources-plugin:2.7:resources (default-resources) @ repo-amp --[INFO] Using 'UTF-8' encoding to copy filtered resources. [INFO] skip non existing resourceDirectory /home/martin/src/alfrescoextensions/all-in-one/repo-amp/src/main/resources [INFO] Copying 16 resources to ../repo-amp [INFO] [INFO] --- yuicompressor-maven-plugin:1.5.1:compress (compress-js) @ repo-amp --[INFO] nothing to do, /home/martin/src/alfresco-extensions/all-in-one/ repo-amp/target/classes/../repo-amp/web/scripts/demoamp-min.js is younger than original, use 'force' option or clean your target [INFO] nb warnings: 0, nb errors: 0 [INFO] [INFO] --- alfresco-maven-plugin:2.1.0-SNAPSHOT:refresh (refreshwebscripts-repo-and-share) @ repo-amp --[INFO] Successfull Refresh Web Scripts for Alfresco Repository [INFO] [INFO] --- maven-compiler-plugin:3.2:compile (default-compile) @ repo-amp --[INFO] Nothing to compile - all classes are up to date [INFO] [INFO] --- alfresco-maven-plugin:2.1.0-SNAPSHOT:refresh-repo (defaultcli) @ repo-amp --[INFO] Successfull Refresh Web Scripts for Alfresco Repository [INFO] -----------------------------------------------------------------------[INFO] BUILD SUCCESS [INFO] -----------------------------------------------------------------------[INFO] Total time: 8.440 s

Developer Guide 65

Developer Guide

[INFO] Finished at: 2015-05-12T12:01:13+01:00 [INFO] Final Memory: 29M/342M [INFO] ------------------------------------------------------------------------

Note that only the repo-amp is built and only the Repository webapp is refreshed (alfresco.war), the Share application is not touched. This demonstrates how you can have better control of the build and refresh when you have a many different AMPs. You can create a similar run configuration for the share-amp project, and for any other AMP project. In this tutorial you have seen how to add and modify code within Eclipse and and then see how these changes take effect immediately, without the need to manually restart or refresh any Alfresco Web Applications. Related Links Rapid Application Development (RAD) on page 52

Importing SDK projects into IntelliJ IDEA The Alfresco SDK is designed to work well with IntelliJ IDEA. This support includes the ability to import existing SDK projects (created via the command line) into IDEA. You should have completed Installing and configuring software and generated a project. You will learn how to import an existing Maven project into IDEA. 1. First, make sure IDEA is using the correct Maven installation (3.2.5 or newer). In the main menu, select File > Settings... . In the IDEA Settings dialog you should see something like this:

66 Alfresco 5.1

Developer Guide

2. Then check that you are using JDK 8, In the main menu, select File > Project Structure... . In the IDEA Project Structure dialog you should see something like this:

3. Now, in the main menu, select File > Open... 4. Navigate to where the project's parent pom is located, in this case the AIO parent pom. You should see a dialog looking something like this when you have located an All-in-One (AIO) project:

Developer Guide 67

Developer Guide

5. Select the pom.xml file for the All-in-One parent project. 6. Click OK. The project is now imported and should appear in the Project tool view to the left. 7. Enable Alfresco Enterprise edition (Optional) If your project is using the Enterprise edition of Alfresco you also want IDEA to load the enterprise versions of the Alfresco WARs and related libraries. You can do this by enable the enterprise profile. In the Maven Projects tool view to the right expand the Profiles folder, then check the enterprise profile. You should see a dialog looking something like this:

68 Alfresco 5.1

Developer Guide

Developer Guide 69

Developer Guide

8. Now use Maven to build the All-in-One (AIO) project. Do this by executing the install command on the parent AIO project. In the Maven Projects tool view to the right expand the parent pom, then expand the Lifecycle folder. You should see a dialog looking something like this:

9. Double-click the install plugin goal. The project will build, and information will be displayed in the Console. You will see a message similar to the following, indicating that the project was successfully built.

70 Alfresco 5.1

Developer Guide

/usr/lib/jvm/java-8-oracle/bin/java -Xms256m -Xmx1G -XX:PermSize=500m javaagent:/home/martin/libs/springloaded-1.2.3.RELEASE.jar -noverify Dmaven.home=/usr/local/apache-maven-3.2.5 ...... install [INFO] Reactor Summary: [INFO] [INFO] Alfresco Repository and Share Quickstart with database and an embedded Tomcat runner. SUCCESS [ 0.387 s] [INFO] Alfresco Repository AMP Module ..................... SUCCESS [ 38.368 s] [INFO] Alfresco Share AMP Module .......................... SUCCESS [ 0.734 s] [INFO] Alfresco Repository WAR Aggregator ................. SUCCESS [ 11.000 s] [INFO] Alfresco Solr 4 Configuration ...................... SUCCESS [ 0.028 s] [INFO] Alfresco Share WAR Aggregator ...................... SUCCESS [ 9.903 s] [INFO] Alfresco, Share and Solr4 Tomcat Runner ............ SUCCESS [ 0.007 s] [INFO] -----------------------------------------------------------------------[INFO] BUILD SUCCESS [INFO] -----------------------------------------------------------------------[INFO] Total time: 01:01 min [INFO] Finished at: 2015-05-06T11:28:02+01:00 [INFO] Final Memory: 61M/503M [INFO] -----------------------------------------------------------------------Process finished with exit code 0

You should see that the MAVEN_OPTS setting has been picked up by IDEA, look at the first line of the log. You have seen how to import your SDK project into IntelliJ and how to build it. Related Links Rapid Application Development (RAD) on page 52

Rapid Application Development in IntelliJ IDEA (Hot reloading) Hot reloading is the ability to modify your application's code, and view the changes without having to restart Alfresco Tomcat. This allows for significant savings in development time that would otherwise be wasted restarting Tomcat. Hot reloading is the key to enabling Rapid Application Development (RAD) and Test Driven Development (TDD). You should have an extension project imported, see importing a project into IDEA. In this tutorial you will see how changes to your code can be carried out without having to restart Alfresco Tomcat. This tutorial demonstrates hot reloading of JavaScript, FreeMarker template, and Java code. There are three components that work together to enable the best RAD experience: 1. Spring Loaded: takes care of hot-reloading any Java class files that we have changed. 2. Refresh Repository Script: This is a script that will POST a request to the Alfresco repository web application (that is, alfresco.war) telling it to refresh the Repo web script container, so any changes to files related to web scripts will be picked up. 3. Refresh Share Script: This is a script that will POST a request to the Alfresco Share web application (that is, share.war) telling it to refresh the Surf web script container, so any

Developer Guide 71

Developer Guide

changes to files related to Surf web scripts will be picked up. This script will also clear the resource dependency caches, so JS changes etc are picked up. Start an instance of Alfresco Tomcat that will be used for hot-reloading. 1. Use the run script to start the Application server with the Alfresco extension project deployed, for example: alfresco-extensions/all-in-one$ ./run.sh

This is usually done outside the IDE. 2. Test the custom repository web script The All-in-One project (and the repository AMP project) have a sample web script included. You can invoke it by pointing your web browser at http://localhost:8080/ alfresco/service/sample/helloworld. If you need to login then use admin with password admin. Running this web script produces the output "Message: Hello World from JS! HelloFromJava". 3. Test the custom Share Aikau Page The All-in-One project (and the Share AMP project) have a sample Aikau page included. You can display it by pointing your web browser at http://localhost:8080/share/ page/hdp/ws/simple-page. If you need to login then use admin with password admin. The page should display as follows:

Enabling Rapid Application Development (RAD) in IDEA. 4. Configure repository AMP projects to Refresh Webapp (alfresco.war) The All-in-One project has one Repository AMP project by default (all-in-one/repo-amp), we need to set up IDEA so that when we build via IDEA (that is, not via Maven) a script runs that will refresh the Repo Web Script container. In the Maven Projects tool view to the right expand the Alfresco Repository AMP Module folder, then expand the Plugins folder. Now expand the alfresco plugin folder. Right click on the alfresco:refresh-repo goal of the plugin. In the drop down menu select Execute After Make. You should now see a dialog looking something like this:

72 Alfresco 5.1

Developer Guide

If you are working with multiple Repo AMPs, then you need to do this configuration for each one of them.

Developer Guide 73

Developer Guide

You only need to do this if you are doing customizations for the Alfresco repository webapp (that is, customizing alfresco.war). If you are just customizing the Share UI, see the next configuration. 5. Configure Share AMP projects to Refresh Webapp (share.war) The All-in-One project has one Share AMP project by default (all-in-one/share-amp), we need to set up IDEA so that when we build via IDEA (that is, not via Maven) a script runs that will refresh the Surf Web Script container and clear dependency caches. In the Maven Projects tool view to the right expand the Alfresco Share AMP Module folder, then expand the Plugins folder. Now expand the alfresco plugin folder. Right click on the alfresco:refresh-share goal of the plugin. In the drop down menu select Execute After Make. You should now see a dialog looking something like this:

74 Alfresco 5.1

Developer Guide

If you are working with multiple Share AMPs, then you need to do this configuration for each one of them.

Developer Guide 75

Developer Guide

You only need to do this if you are doing customizations for the Alfresco Share webapp (that is, customizing share.war). If you are just customizing the repository, see the previous configuration. Testing RAD when doing repository customizations (alfresco.war). 6. In the Project Explorer, navigate to and expand the all-in-one/repo-amp/src/main/ amp/config/alfresco/extension/templates/webscripts folder 7. Locate the helloworld.get.js file and load it into the editor by double-clicking it. This is the controller for the web script that we tried after starting the server. Update the controller code by adding an 'UPDATED' string as follows: model["fromJS"] = "Hello World from JS! UPDATED";

8. Now build(Make) the project by clicking Ctrl+F9 The message console in IDEA should display BUILD SUCCESS for both the repo-amp and share-amp modules as follows: [INFO] Scanning for projects... [INFO] [INFO] -----------------------------------------------------------------------[INFO] Building Alfresco Repository AMP Module 1.0-SNAPSHOT [INFO] -----------------------------------------------------------------------[INFO] [INFO] --- alfresco-maven-plugin:2.1.0-SNAPSHOT:refresh-repo (defaultcli) @ repo-amp --[INFO] Successfull Refresh Web Scripts for Alfresco Repository [INFO] -----------------------------------------------------------------------[INFO] BUILD SUCCESS [INFO] -----------------------------------------------------------------------[INFO] Total time: 3.854 s [INFO] Finished at: 2015-05-11T10:20:17+01:00 [INFO] Final Memory: 15M/315M [INFO] -----------------------------------------------------------------------[INFO] Scanning for projects... [INFO] [INFO] -----------------------------------------------------------------------[INFO] Building Alfresco Share AMP Module 1.0-SNAPSHOT [INFO] -----------------------------------------------------------------------[INFO] [INFO] --- alfresco-maven-plugin:2.1.0-SNAPSHOT:refresh-share (defaultcli) @ share-amp --[INFO] Successfull Refresh Web Scripts for Alfresco Share [INFO] Successfull Clear Dependency Caches for Alfresco Share [INFO] -----------------------------------------------------------------------[INFO] BUILD SUCCESS [INFO] -----------------------------------------------------------------------[INFO] Total time: 4.173 s [INFO] Finished at: 2015-05-11T10:20:24+01:00 [INFO] Final Memory: 18M/309M [INFO] ------------------------------------------------------------------------

76 Alfresco 5.1

Developer Guide

[INFO] Maven execution finished

Note the refresh calls to the web applications. If you would prefer to only refresh the repository webapp (that is, alfresco.war) have a look later on in this article for a different approach to refreshing the webapp via run configurations. 9. Refresh the http://localhost:8080/alfresco/service/sample/helloworld Repository Web Script page from the Browser The output from the web script should change to "Message: Hello World from JS! UPDATED HelloFromJava". Note that there is no need to restart the application server, just a Make of the project, and a refresh of the web script page from the browser (you are basically invoking the web script again and the update should be immediately visible). 10.

Now locate the helloworld.get.html.ftl file and double-click it to load it into the editor. This is the FreeMarker template for the web script. Update the template by adding an 'ExtraTemplateText' string as follows: Message: ${fromJS} ${fromJava} ExtraTemplateText

11.

Now build(Make) the project by clicking Ctrl+F9 The message console in IDEA should display BUILD SUCCESS

12.

Refresh the http://localhost:8080/alfresco/service/sample/helloworld Repository Web Script page from the Browser The output from the web script should change to "Message: Hello World from JS! UPDATED HelloFromJava ExtraTemplateText ". Again, note that there is no need to restart the application server, only a Make of the project and a refresh of the web script page are necessary.

13.

In the next demo we will add a properties file for the web script, create a helloworld.get.properties file next to the other files we have been working with. The properties file should have one property as follows: hello.word.extras=Extra Stuff From Props

14.

Add this property to the template, open up helloworld.get.html.ftl. The FreeMarker template should now look like this: Message: ${fromJS} ${fromJava} ${msg("hello.word.extras")}

15.

ExtraTemplateText

Now build(Make) the project by clicking Ctrl+F9 The message console in IDEA should display BUILD SUCCESS.

16.

Refresh the http://localhost:8080/alfresco/service/sample/helloworld Repository Web Script page from the Browser The output of the web script should change to "Message: Hello World from JS! UPDATED HelloFromJava ExtraTemplateText Extra Stuff From Props". No restart of application server should be needed, just a Make of the project and a refresh of the web script page from the browser.

17.

In the last web script demo we will change the Java controller

18.

Open up all-in-one/repo-amp/src/main/java/{your package path}/demoamp/ HelloWorldWebScript.java.

Developer Guide 77

Developer Guide

Change the property text as follows: public class HelloWorldWebScript extends DeclarativeWebScript { protected Map executeImpl( WebScriptRequest req, Status status, Cache cache) { Map model = new HashMap(); model.put("fromJava", "HelloFromJavaUPDATED"); return model; } }

19.

Now build(Make) the project by clicking Ctrl+F9 The message console in IDEA should display BUILD SUCCESS.

20.

Refresh the http://localhost:8080/alfresco/service/sample/helloworld Repository Web Script page from the Browser The output of the web script should change to "Message: Hello World from JS! UPDATED HelloFromJavaUPDATED ExtraTemplateText Extra Stuff From Props". No restart of application server should be needed, just a Make of the project and a refresh of the web script page from the browser.

Test Driven Development (TDD) and RAD when doing Repository customizations (alfresco.war). 21.

In the IntelliJ Project Explorer expand all-in-one/repo-amp/src/test/java/{your package path}/demoamp/test and then locate the DemoComponentTest.java source file.

22.

Load it into the editor by double-clicking it.

23.

Now set up a Run Configuration to run repo-amp tests. From the main menu select Run > Edit Configurations .

24.

In the Run/Debug Configurations dialog, click '+' to create a new configuration. Select Maven from the list of available configuration types.

25.

Set the Name field of the configuration to "Test Repo AMP".

26.

Set the Working Directory field of the configuration to "alfresco-extensions/all-in-one/ repo-amp".

27.

Set the Command line field "test".

28.

Click OK.

29.

Now run the test by selecting Run > Run 'Test Repo AMP' from the main menu. The test will run, and three tests will pass:

/usr/lib/jvm/java-8-oracle/bin/java -Xms256m -Xmx1G -javaagent:/home/ martin/libs/springloaded-1.2.3.RELEASE.jar -noverify -Dmaven.home=/usr/ local/apache-maven-3.2.5 .... [INFO] Scanning for projects... [INFO] [INFO] -----------------------------------------------------------------------[INFO] Building Alfresco Repository AMP Module 1.0-SNAPSHOT [INFO] -----------------------------------------------------------------------[INFO] [INFO] --- alfresco-maven-plugin:2.1.0-SNAPSHOT:set-version (default-setversion) @ repo-amp --[INFO] Removed -SNAPSHOT suffix from version - 1.0 [INFO] Added timestamp to version - 1.0.1505120757

78 Alfresco 5.1

Developer Guide

[INFO] [INFO] --- build-helper-maven-plugin:1.9.1:add-test-resource (add-envtest-properties) @ repo-amp --[INFO] [INFO] --- maven-resources-plugin:2.7:resources (default-resources) @ repo-amp --[INFO] Using 'UTF-8' encoding to copy filtered resources. [INFO] skip non existing resourceDirectory /home/martin/src/alfrescoextensions/all-in-one/repo-amp/src/main/resources [INFO] Copying 14 resources to ../repo-amp [INFO] [INFO] --- yuicompressor-maven-plugin:1.5.1:compress (compress-js) @ repo-amp --[INFO] nothing to do, /home/martin/src/alfresco-extensions/all-in-one/ repo-amp/target/classes/../repo-amp/web/scripts/demoamp-min.js is younger than original, use 'force' option or clean your target [INFO] nb warnings: 0, nb errors: 0 [INFO] [INFO] --- alfresco-maven-plugin:2.1.0-SNAPSHOT:refresh (refreshwebscripts-repo-and-share) @ repo-amp --[INFO] Successfull Refresh Web Scripts for Alfresco Repository [INFO] [INFO] --- maven-compiler-plugin:3.2:compile (default-compile) @ repo-amp --[INFO] Nothing to compile - all classes are up to date [INFO] [INFO] --- maven-resources-plugin:2.7:testResources (defaulttestResources) @ repo-amp --[INFO] Using 'UTF-8' encoding to copy filtered resources. [INFO] Copying 2 resources [INFO] Copying 1 resource [INFO] [INFO] --- maven-resources-plugin:2.7:copy-resources (add-moduleproperties-to-test-classpath) @ repo-amp --[INFO] Using 'UTF-8' encoding to copy filtered resources. [INFO] Copying 1 resource to alfresco/module/repo-amp [INFO] [INFO] --- maven-resources-plugin:2.7:copy-resources (add-module-configto-test-classpath) @ repo-amp --[INFO] Using 'UTF-8' encoding to copy filtered resources. [INFO] Copying 9 resources [INFO] [INFO] --- maven-compiler-plugin:3.2:testCompile (default-testCompile) @ repo-amp --[INFO] Nothing to compile - all classes are up to date [INFO] [INFO] --- maven-surefire-plugin:2.18:test (default-test) @ repo-amp --[INFO] Surefire report directory: /home/martin/src/alfresco-extensions/ all-in-one/repo-amp/target/surefire-reports ------------------------------------------------------T E S T S ------------------------------------------------------Running org.alfresco.allinone.demoamp.test.DemoComponentTest Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.085 sec - in org.alfresco.allinone.demoamp.test.DemoComponentTest Results : Tests run: 3, Failures: 0, Errors: 0, Skipped: 0 [INFO] -----------------------------------------------------------------------[INFO] BUILD SUCCESS [INFO] -----------------------------------------------------------------------[INFO] Total time: 6.946 s [INFO] Finished at: 2015-05-12T07:57:24+01:00

Developer Guide 79

Developer Guide

[INFO] Final Memory: 25M/443M [INFO] ------------------------------------------------------------------------

30.

Now, in DemoComponentTest.java, modify one of the tests so that it will fail. For example, you could change the line assertEquals(7, childNodeCount); to assertEquals(8, childNodeCount);

31.

Now run the test again by right-clicking the file in Project Explorer and selecting Run 'Test Repo AMP'. Note the test will run again and this time fail. But you did not need to restart Alfresco. This demonstrates hot reloading of Java code.

32.

Change the code back and re-run the test. Now you will see that all tests pass. The code has re-run without any reloading of Alfresco! This allows for Test Driven Development with very low overhead.

Testing RAD when doing Share customizations (share.war). 33.

In the Project Explorer, navigate to and expand the all-in-one/share-amp/src/main/ amp/config/alfresco/web-extension/site-webscripts/com/example/pages folder

34.

Locate the simple-page.get.js file and load it into the editor by double-clicking it. This is the controller for the Aikau Page web script that we tried after starting the server. Update the controller code by adding an 'UPDATED' string as follows to the page title, also change the layout from HorizontalWidgets to VerticalWidgets: model.jsonModel = { widgets: [{ id: "SET_PAGE_TITLE", name: "alfresco/header/SetTitle", config: { title: "This is a simple page UPDATED" } }, { id: "MY_HORIZONTAL_WIDGET_LAYOUT", name: "alfresco/layout/VerticalWidgets", config: { widgetWidth: 50, widgets: [ { id: "DEMO_SIMPLE_LOGO", name: "alfresco/logo/Logo", config: { logoClasses: "alfresco-logo-only" } }, { id: "DEMO_SIMPLE_MSG", name: "example/widgets/TemplateWidget" } ] } }] };

35.

Now build(Make) the project by clicking Ctrl+F9 The message console in IDEA should display BUILD SUCCESS for both the repo-amp and share-amp modules as follows:

80 Alfresco 5.1

Developer Guide

[INFO] Scanning for projects... [INFO] [INFO] -----------------------------------------------------------------------[INFO] Building Alfresco Repository AMP Module 1.0-SNAPSHOT [INFO] -----------------------------------------------------------------------[INFO] [INFO] --- alfresco-maven-plugin:2.1.0-SNAPSHOT:refresh-repo (defaultcli) @ repo-amp --[INFO] Successfull Refresh Web Scripts for Alfresco Repository [INFO] -----------------------------------------------------------------------[INFO] BUILD SUCCESS [INFO] -----------------------------------------------------------------------[INFO] Total time: 3.854 s [INFO] Finished at: 2015-05-11T10:20:17+01:00 [INFO] Final Memory: 15M/315M [INFO] -----------------------------------------------------------------------[INFO] Scanning for projects... [INFO] [INFO] -----------------------------------------------------------------------[INFO] Building Alfresco Share AMP Module 1.0-SNAPSHOT [INFO] -----------------------------------------------------------------------[INFO] [INFO] --- alfresco-maven-plugin:2.1.0-SNAPSHOT:refresh-share (defaultcli) @ share-amp --[INFO] Successfull Refresh Web Scripts for Alfresco Share [INFO] Successfull Clear Dependency Caches for Alfresco Share [INFO] -----------------------------------------------------------------------[INFO] BUILD SUCCESS [INFO] -----------------------------------------------------------------------[INFO] Total time: 4.173 s [INFO] Finished at: 2015-05-11T10:20:24+01:00 [INFO] Final Memory: 18M/309M [INFO] -----------------------------------------------------------------------[INFO] Maven execution finished

Also, note the refresh calls to the Web Applications to refresh. If you would prefer to only refresh the Share webapp (that is, share.war) have a look later on in this article for a different approach to refreshing the webapp via run configurations. 36.

Refresh the http://localhost:8080/share/page/hdp/ws/simple-page Aikau Page from the Browser The page should now display as follows:

Developer Guide 81

Developer Guide

37.

Now, let's update some HTML, CSS, and Properties for the sample widget that is used by the Aikau page, navigate to and expand the all-in-one/share-amp/src/main/amp/ web/js/example/widgets folder

38.

Locate the css/TemplateWidget.css file and load it into the editor by double-clicking it. This is the Stylesheet for the Aikau Widget. Update the widget style as follows: .my-template-widget { border: 2px #000000 solid; padding: 1em; width: 100px; color: white; background-color: blue; }

39.

Then locate the i18n/TemplateWidget.properties file and load it into the editor by double-clicking it. This is the resource file for the Aikau Widget. Update the properties as follows: hello-label=Hello from i18n UPDATED! hello-test=Going to use this label too now!

40.

Then locate the templates/TemplateWidget.html file and load it into the editor by double-clicking it. This is the HTML template file for the Aikau Widget. Update so it looks as follows: ${greeting} and ${greeting2}

41.

And finally, locate the TemplateWidget.js file and load it into the editor by double-clicking it. This is the main JavaScript implementation for the Aikau Widget. Update so it also sets the new property used in template: define(["dojo/_base/declare", "dijit/_WidgetBase", "alfresco/core/Core",

82 Alfresco 5.1

Developer Guide

"dijit/_TemplatedMixin", "dojo/text!./templates/TemplateWidget.html" ], function(declare, _Widget, Core, _Templated, template) { return declare([_Widget, Core, _Templated], { templateString: template, i18nRequirements: [ {i18nFile: "./i18n/ TemplateWidget.properties"} ], cssRequirements: [{cssFile:"./css/TemplateWidget.css"}], buildRendering: function example_widgets_TemplateWidget__buildRendering() { this.greeting = this.message('hello-label'); this.greeting2 = this.message('hello-test'); this.inherited(arguments); } }); });

42.

Now build(Make) the project by clicking Ctrl+F9.

43.

Refresh the http://localhost:8080/share/page/hdp/ws/simple-page Aikau Page from the Browser. The page should now display as follows:

Enabling RAD in IDEA with run configurations. 44.

Introduction In this article we have seen how we can achieve Rapid Application Development within IDEA by executing alfresco maven plugin refresh goals after a Make. This is an easy way to configure RAD in IDEA when you are only working with 1 or 2 AMPs. However, when you start to get a number of AMPs that you are working on simultaneously, then there will be a lot of refresh calls going on as every AMP's alfresco plugin goal config will be executed. This could be seen in the tutorials above where the refresh-share and refresh-repo goals were always executed even if we were just working with one of the

Developer Guide 83

Developer Guide

associated AMPs. In the following tutorial you will see how run configurations can be used for better control of when the refresh call is being made. 45.

Set up a Run Configuration to run repo-amp builds and Repository webapp refresh (alfresco.war). From the main menu select Run > Edit Configurations .

46.

In the Run/Debug Configurations dialog, click '+' to create a new configuration. Select Maven from the list of available configuration types.

47.

Set the Name field of the configuration to "Make Repo AMP".

48.

Set the Working Directory field of the configuration to "alfresco-extensions/all-in-one/ repo-amp".

49.

Set the Command line field "compile alfresco:refresh-repo".

50.

Click OK.

51.

Now do a Make(build) by selecting Run > Run 'Make Repo AMP' from the main menu. The build will run with the following result:

/usr/lib/jvm/java-8-oracle/bin/java -Xms256m -Xmx1G -javaagent:/home/ martin/libs/springloaded-1.2.3.RELEASE.jar -noverify -Dmaven.home=/usr/ local/apache-maven-3.2.5 .... [INFO] Scanning for projects... [INFO] [INFO] -----------------------------------------------------------------------[INFO] Building Alfresco Repository AMP Module 1.0-SNAPSHOT [INFO] -----------------------------------------------------------------------[INFO] [INFO] --- alfresco-maven-plugin:2.1.0-SNAPSHOT:set-version (default-setversion) @ repo-amp --[INFO] Removed -SNAPSHOT suffix from version - 1.0 [INFO] Added timestamp to version - 1.0.1505120823 [INFO] [INFO] --- build-helper-maven-plugin:1.9.1:add-test-resource (add-envtest-properties) @ repo-amp --[INFO] [INFO] --- maven-resources-plugin:2.7:resources (default-resources) @ repo-amp --[INFO] Using 'UTF-8' encoding to copy filtered resources. [INFO] skip non existing resourceDirectory /home/martin/src/alfrescoextensions/all-in-one/repo-amp/src/main/resources [INFO] Copying 14 resources to ../repo-amp [INFO] [INFO] --- yuicompressor-maven-plugin:1.5.1:compress (compress-js) @ repo-amp --[INFO] nothing to do, /home/martin/src/alfresco-extensions/all-in-one/ repo-amp/target/classes/../repo-amp/web/scripts/demoamp-min.js is younger than original, use 'force' option or clean your target [INFO] nb warnings: 0, nb errors: 0 [INFO] [INFO] --- alfresco-maven-plugin:2.1.0-SNAPSHOT:refresh (refreshwebscripts-repo-and-share) @ repo-amp --[INFO] Successfull Refresh Web Scripts for Alfresco Repository [INFO] [INFO] --- maven-compiler-plugin:3.2:compile (default-compile) @ repo-amp --[INFO] Nothing to compile - all classes are up to date [INFO] [INFO] --- alfresco-maven-plugin:2.1.0-SNAPSHOT:refresh-repo (defaultcli) @ repo-amp --[INFO] Successfull Refresh Web Scripts for Alfresco Repository

84 Alfresco 5.1

Developer Guide

[INFO] -----------------------------------------------------------------------[INFO] BUILD SUCCESS [INFO] -----------------------------------------------------------------------[INFO] Total time: 6.389 s [INFO] Finished at: 2015-05-12T08:23:57+01:00 [INFO] Final Memory: 30M/490M [INFO] ------------------------------------------------------------------------

Note that only the repo-amp is built and only the repository webapp is refreshed (alfresco.war), the Share application is not touched. This demonstrates how you can have better control of the build and refresh when you have a many different AMPs. You can create a similar run configuration for the share-amp project, and for any other AMP project. In this tutorial you have seen how to add and modify code within IntelliJ IDEA and then see how these changes take effect immediately, without the need to manually restart or refresh any Alfresco web applications. Related Links Rapid Application Development (RAD) on page 52

Remote debugging with an IDE It is possible to start an application ready for remote debugging by using the Maven mvnDebug command.Eclipse or another development environment such as IDEA can then connect to the running application for remote debugging. You should have an extension project imported, see importing a project into Eclipse. It is quite common that you would need to debug Java code associated with an Alfresco extension you are developing. For example, if you are developing a Java backed Web Script. The command mvnDebug can be used to start the application in remote debugging mode, where it will listen on port 8000, ready for a remote debugger to attach. 1. In this tutorial we assume that we are working with an All-in-One (AIO) project, change into the top directory (alfresco-extensions/all-in-one). Start the AIO project in debug mode. 2. Run mvnDebug rather than the mvn command: $ mvnDebug clean install -Prun Preparing to Execute Maven in Debug Mode Listening for transport dt_socket at address: 8000 ...

The Maven project will start and listen for a remote debugger on port 8000. This is usually done outside the IDE. Connect to the running application process from Eclipse 3. In Eclipse, select Run > Debug Configurations from the main menu. 4. Select Remote Java Application and click the New icon on the top left of the dialog. 5. Give the Debug Configuration a suitable name, such as "Debug Alfresco Extension". 6. Click Browse and select the repo-amp project, the rest of the fields for host and port have suitable default values.

Developer Guide 85

Developer Guide

7. Click Apply. 8. Click Debug to run the Debug Configuration and connect to the remote Alfresco server. 9. In Eclipse, enable the Debug perspective by selecting Window > Open Perspective > Debug from the main menu. 10.

Set a breakpoint in the all-in-one/repo-amp/src/main/java/org/alfresco/ allinone/demoamp/HelloWorldWebScript.java) file.

11.

Invoke the http://localhost:8080/alfresco/service/sample/helloworld Repository Web Script from the Browser You should now see the process stopping in the debugger as follows:

Related Links Rapid Application Development (RAD) on page 52

Advanced Topics This information provides more advanced topics that you might come in contact with when you have been working with an SDK project for a while. We will have a look at how you can add more custom modules to an All-in-One project, how to bring in standard Alfresco modules such as Records Management (RM) and SharePoint Protocol (SPP) support, configuring SSL, and more.

86 Alfresco 5.1

Developer Guide

Configure SSL between Repository and Solr in an AIO project The SDK ships with SSL turned off between the Alfresco Repository and the Solr 4 search server. This article explains how to set that up when running an All-in-One (AIO) project. You should have completed Installing and Configuring software and generated an AIO project. You will also need access to an Alfresco 5 installation as we need to copy the keystore and Tomcat users file from it. You will learn how to setup a secure connection (SSL) between the Alfresco Repository web application (alfresco.war) and the Apache Solr 4 web application (alfresco-solr4.war). This is the normal configuration after you have installed Alfresco with a package installer. In the following instructions ALFRESCO_INSTALL_DIR is the directory path to where you installed Alfresco 5 with the package installer (for example /opt/alfresco5). And AIO_PARENT_DIR points to where the parent project directory is for the All-in-One (AIO) project (for example /home/martin/src/all-inone). 1. Stop the embedded Tomcat instance, if it is running. 2. Copy the Repository keystore to the AIO project. Execute the following command to copy the keystore into the runner project: {ALFRESCO_INSTALL_DIR}/alf_data$ cp -R keystore/ {AIO_PARENT_DIR}/runner/

We can now configure the embedded Tomcat instace to use this keystore. 3. Copy Tomcat users definition to the AIO project. Execute the following command to copy the tomcat users file into the runner project: {AIO_PARENT_DIR}/runner/tomcat$ mkdir conf {ALFRESCO_INSTALL_DIR}/tomcat/conf$ cp tomcat-users.xml {AIO_PARENT_DIR}/ runner/tomcat/conf/

What we do here is first create a directory to hold the tomcat users file. And then we copy the tomcat users file from the Alfresco installation to this new directory in the runner project. This file contains identities for the Repository and Solr applications when setting up SSL connections. 4. Turn on SSL for Repository. Open up the alfresco-global.properties file located in the {AIO_PARENT_DIR}/repo/ src/main/properties/local directory. Then update the section about Solr configuration: index.subsystem.name=solr4 dir.keystore={AIO_PARENT_DIR}/runner/keystore solr.host=localhost solr.port=8080 solr.port.ssl=8443 #solr.secureComms=none

Note. You have to change {AIO_PARENT_DIR} to whatever the parent directory is for your AIO project. 5. Update the tomcat7-maven-plugin with keystore, port, and Tomcat users Open up the pom.xml file located in the {AIO_PARENT_DIR}/runner directory. Then update the plugin configuration as follows: org.apache.tomcat.maven tomcat7-maven-plugin run-wars run

Developer Guide 87

Developer Guide

pre-integration-test 8443 ${project.basedir}/keystore/ssl.keystore kT9X6oe68t JCEKS ${project.basedir}/keystore/ssl.truststore kT9X6oe68t JCEKS ${project.basedir}/tomcat/conf/tomcat-users.xml

6. Change Solr4 configuration package to the one that has SSL enabled. Open up the pom.xml file located in the {AIO_PARENT_DIR}/solr-config directory. Then update the dependency and plugin configuration as follows: org.alfresco alfresco-solr4 ${alfresco.version} config-ssl zip org.apache.maven.plugins maven-dependency-plugin unpack-alfresco-config unpack generate-resources ${alfresco.solr.home.dir} org.alfresco alfresco-solr4 ${alfresco.version} config-ssl zip

This Solr4 configuration comes preconfigured with SSL enabled, keystore and truststore, including the keystores themselves. 7. Delete previous "no-ssl" configuration directory. {AIO_PARENT_DIR}/alf_data_dev/solr4$ rm -rf config/

This is so the new SSL enabled configuration is downloaded and installed correctly under alf_data_dev. 8. Make sure that the Alfresco Repository (alfresco.war) web application is using SSL.

88 Alfresco 5.1

Developer Guide

Open up the pom.xml file located in the {AIO_PARENT_DIR}/repo directory. Then update the maven-war-plugin configuration as follows: maven-war-plugin prepare-exploded-war exploded prepare-package default-war

What we do here is just commenting out the web.xml file that we normally use when we don't want to use SSL. 9. Start it up and make sure it works. You should see something like this in the logs: {AIO_PARENT_DIR}$ mvn clean install -Prun ... Jun 05, 2015 10:56:33 AM org.apache.coyote.AbstractProtocol start INFO: Starting ProtocolHandler ["http-bio-8080"] Jun 05, 2015 10:56:33 AM org.apache.coyote.AbstractProtocol start INFO: Starting ProtocolHandler ["http-bio-8443"]

Try accessing Share securely: https://localhost:8443/share. Make sure search works by adding a text file with a unique word, then search for it. Then access Solr4 securely: https://localhost:8443/solr4. You have now setup SSL between the Alfresco Repository and the Solr4 server. Related Links Advanced Topics on page 86

Adding internal and external JARs to a Repository AMP project This article explains how to add an external JAR to a Repository AMP project via a dependency. It also looks at how to extract some AMP code into its own JAR project, what we call an internal JAR, and then have the AMP project include it. This tutorial assumes that you have completed Installing and Configuring software and generated a Repo AMP project. To try out the examples in this article you will need to install a local SMTP server such as Fake SMTP. Sometimes when you are developing a Repository AMP you need to include external libraries (JARs) that are not part/are not available in the tomcat/webapps/alfresco/WEBINF/lib directory. Being able to do this is one of the benefits of AMPs compared to other extension models. The Repository AMP might also start to grow to a size where it would make sense to move some of the functionality over to separate JAR projects, and have the AMP depend on them. This article goes through how to do these things. Adding an external JAR to a Repository AMP project. An external JAR is needed when you want to use some library that is not part of the Alfresco Repository (alfresco.war) web application. Meaning it is not present in the

Developer Guide 89

Developer Guide

tomcat/webapps/alfresco/WEB-INF/lib directory. So you should always first scan this

directory in an Alfresco Community Edition or Enterprise installation to see if the library is available. If it is available, then you can include it in the componentX-repo/pom.xml as a provided dependency. In the following example we will update the Hello World Web Script code (it is part of the Repository AMP source code) so that it can send emails. However, when we select a Mail library to use for this, we forget to check if the library is already available as part of the Alfresco Repository WAR. We will see what happens then and how to fix it: 1. Stop the embedded Tomcat instance, if it is running (i.e. via -Pamp-to-war). 2. Find a library that can be used to send emails from Java and add a dependency for it to the Repo AMP project. We know that the Java Mail library can be used for this, so we look up the maven dependency for it and add it to the componentX-repo/pom.xml: ... ${alfresco.groupId} alfresco-repository com.sun.mail javax.mail 1.5.3 ...

We can now start implementing some code that uses the Java Mail library. 3. Update the Hello World Web Script to send an email. The implementation can be done as follows in the Java controller (componentX-repo/ src/main/java/com/acme/componentX/demoamp/HelloWorldWebScript.java): import import import import import import import import

javax.mail.*; javax.mail.internet.InternetAddress; javax.mail.internet.MimeBodyPart; javax.mail.internet.MimeMessage; javax.mail.internet.MimeMultipart; java.util.HashMap; java.util.Map; java.util.Properties;

/** * A demonstration Java controller for the Hello World Web Script. * * @author [email protected] * @since 2.1.0 */ public class HelloWorldWebScript extends DeclarativeWebScript { protected Map executeImpl( WebScriptRequest req, Status status, Cache cache) { Map model = new HashMap(); model.put("fromJava", "HelloFromJava"); sendEmail(); return model; } private void sendEmail() { String to = "[email protected]"; String subject = "Test email from Web Script"; String body = "Hello World!";

90 Alfresco 5.1

Developer Guide

try { // Create mail session Properties props = new Properties(); props.put("mail.smtp.host", ""); // localhost will not work props.put("mail.smtp.port", "2525"); // non-privileged port Session session = Session.getDefaultInstance(props, null); session.setDebug(false); // Define message Message message = new MimeMessage(session); String fromAddress = "[email protected]"; message.setFrom(new InternetAddress(fromAddress)); message.addRecipient(Message.RecipientType.TO, new InternetAddress(to)); message.setSubject(subject); // Create the message part with body text BodyPart messageBodyPart = new MimeBodyPart(); messageBodyPart.setText(body); Multipart multipart = new MimeMultipart(); multipart.addBodyPart(messageBodyPart); // Put parts in message message.setContent(multipart); // Send the message Transport.send(message); } catch (MessagingException me) { me.printStackTrace(); } } }

For the code to work you will need to update to whatever hostname your machine has. The code uses standard Java Mail classes to send a simple email without attachments. 4. Build the Repository AMP. Standing in the Repo AMP project directory, type the following Maven command: componentX-repo$ mvn clean install -DskipTests=true

What we end up with now is a Repository AMP with the following JARs:

Developer Guide 91

Developer Guide

This might seem okay at first, but it is actually not a good idea. When we apply this AMP to an Alfresco5.WAR file, the JAR files will be added to the tomcat/webapps/alfresco/ WEB-INF/lib directory, and we end up with duplicate Java Mail libraries as it already contains one version of the library:

92 Alfresco 5.1

Developer Guide

So the correct approach is to always check what JARs that are available in the Alfresco 5 WAR, and then for any JAR that is available use provided when specifying the dependency for it. 5. Update the Java Mail dependency to have scope provided. Open up the componentX-repo/pom.xml and update the Java Mail dependency as follows: ... ${alfresco.groupId} alfresco-repository com.sun.mail javax.mail 1.5.3 provided ...

This will mean that the Java Mail JAR is not included in the AMP but we can still compile and build against it, which is what we want. So to summarize, if the JAR is not in tomcat/webapps/alfresco/WEB-INF/lib, then do not use provided scope as you want it included with the AMP. On the other hand, if the JAR is available, then use provided scope to exclude it from the AMP deliverable. Adding an internal JAR to a Repository AMP project. Another requirement that might come up when you are working with a Repository AMP project is that it is growing big, so big that it would make sense to move some AMP project code into its own JAR projects, but still have those part of the same AMP build. Basically turning the Repository AMP project into a multi-module project. So let’s demonstrate how to do this by moving the Hello World Web Script code into its own JAR module and have the AMP dependent on it. 6. Create a Repository AMP parent project directory. To achieve what we want, we will have to turn the Repository AMP project into a multimodule project, and for this we need a parent project. Create a new directory called componentX-parent and then copy the Repository AMP directory into it: componentX-repo$ cd .. ~/src/$ mkdir componentX-parent ~/src/$ mv componentX-repo/ componentX-parent/

7. Create a Repository AMP parent project POM file. Add the following pom.xml to the componentX-parent directory: 4.0.0 com.acme componentX-parent 1.0-SNAPSHOT componentX-repo Repository AMP parent This is the parent project for the multi-module componentX-repo Repository AMP project pom

Developer Guide 93

Developer Guide

org.alfresco.maven alfresco-sdk-parent 2.2.0 componentX-repo

Note how this parent project now has the SDK Project as a parent. And it includes the Repository AMP project as a sub-module. The parent project packaging is pom, which means it is not producing an artefact like a JAR, AMP, or WAR, it just acts as a parent for other sub-modules. 8. Update parent definition in the Repository AMP project POM file. Open up the componentX-parent/componentX-repo/pom.xml file. Then update the parent definition as follows: 4.0.0 componentX-repo componentX-repo Repository AMP project amp Manages the lifecycle of the componentX-repo Repository AMP (Alfresco Module Package) com.acme componentX-parent 1.0-SNAPSHOT ...

Note the parent section and how it now points to our new parent. Also, we have removed the version and groupId properties from the AMP project as they are inherited from the parent project. 9. Build the Repository AMP parent project. You should see something like this in the logs: componentX-parent$ mvn clean install -DskipTests=true . . . [INFO] Reactor Summary: [INFO] [INFO] componentX-repo Repository AMP parent .............. SUCCESS [ 0.607 s] [INFO] componentX-repo Repository AMP project ............. SUCCESS [ 6.850 s] [INFO] -----------------------------------------------------------------------[INFO] BUILD SUCCESS

So we now got a parent project that can contain more sub-projects then just the Repository AMP project. 10.

Add a JAR project and move the Hello World Web Script code. We are going to create a new JAR sub-project and then move the Hello World Web Script code over to it from the AMP. Let’s start by adding a new JAR project. Stand in the parent

94 Alfresco 5.1

Developer Guide

directory and issue the following command, which will generate a starting point for a JAR module: componentX-parent$ mvn archetype:generate -DgroupId=com.acme DartifactId=componentX-web-script -DarchetypeArtifactId=maven-archetypequickstart -DinteractiveMode=false

We are using the Maven Quickstart archetype to generate the JAR module. Our parent directory now looks like this: componentX-parent$ ls -l total 16 drwxrwxr-x 6 martin martin 4096 Jun drwxrwxr-x 3 martin martin 4096 Jun -rw-rw-r-- 1 martin martin 881 Jun

5 15:27 componentX-repo 5 15:35 componentX-web-script 5 15:35 pom.xml

When we generate a new module from the parent directory it is automatically added to the modules section of the parent POM as follows: ... componentX-repo componentX-web-script

And the parent section is setup correctly also in the new JAR module, open up componentX-parent/componentX-web-script/pom.xml and have a look: 4.0.0 com.acme componentX-parent 1.0-SNAPSHOT componentX-web-script componentX-web-script JAR project http://maven.apache.org ...

You might notice that I have removed the version and groupId properties from the JAR project as they are inherited from our parent project. I also updated the name so it is easy to see what type of artefact that is produced. 11.

Build the Repository AMP parent project. You should see something like this in the logs: componentX-parent$ mvn clean install -DskipTests=true . . . [INFO] Reactor Summary: [INFO] [INFO] componentX-repo Repository AMP parent .............. SUCCESS [ 0.685 s] [INFO] componentX-repo Repository AMP project ............. SUCCESS [ 7.131 s] [INFO] componentX-web-script JAR project .................. SUCCESS [ 0.539 s] [INFO] -----------------------------------------------------------------------[INFO] BUILD SUCCESS

12.

Move the Hello World Web Script files over to the new JAR project.

Developer Guide 95

Developer Guide

Here we are doing this via command line: componentX-parent$ cd componentX-web-script/ componentX-parent/componentX-web-script$ cd src/main/java/com/acme/ componentX-parent/componentX-web-script/src/main/java/com/acme$ mkdir componentX componentX-parent/componentX-web-script/src/main/java/com/acme$ cd componentX/ componentX-parent/componentX-web-script/src/main/java/com/acme/componentX $ mkdir demoamp componentX-parent/componentX-web-script/src/main/java/com/acme/componentX $ cd demoamp/ componentX-parent/componentX-web-script/src/main/java/com/acme/ componentX/demoamp$ mv ~/src/componentX-parent/componentX-repo/src/main/ java/com/acme/componentX/demoamp/HelloWorldWebScript.java . componentX-parent/componentX-web-script/src/main/java/com/acme/ componentX/demoamp$ cd ../../../../../ componentX-parent/componentX-web-script/src/main$ mkdir resources componentX-parent/componentX-web-script/src/main$ cd resources/ componentX-parent/componentX-web-script/src/main/resources$ mkdir alfresco componentX-parent/componentX-web-script/src/main/resources$ cd alfresco/ componentX-parent/componentX-web-script/src/main/resources/alfresco$ mkdir extension componentX-parent/componentX-web-script/src/main/resources/alfresco$ cd extension/ componentX-parent/componentX-web-script/src/main/resources/alfresco/ extension$ mkdir templates componentX-parent/componentX-web-script/src/main/resources/alfresco/ extension$ cd templates/ componentX-parent/componentX-web-script/src/main/resources/alfresco/ extension/templates$ mkdir webscripts componentX-parent/componentX-web-script/src/main/resources/alfresco/ extension/templates$ cd webscripts/ componentX-parent/componentX-web-script/src/main/resources/alfresco/ extension/templates/webscripts$ mv ~/src/componentX-parent/componentXrepo/src/main/amp/config/alfresco/extension/templates/webscripts/* .

If you have followed along, then you should see something like this in your IDE now:

96 Alfresco 5.1

Developer Guide

Developer Guide 97

Developer Guide

We are not moving the spring context file with the Java controller bean definition over to the JAR project as we want there only to be one module bringing in the spring context (i.e. the Repository AMP Module). We are just keeping the Web Script files in a separate JAR to be able to work with them in an easier way. It will also give us the opportunity to completely lift out this JAR as a stand-alone project in the future, and release it separately to Nexus, if we should want to do that. 13.

Move the Java Mail dependency from the AMP project to the JAR project. Open up the componentX-parent/componentX-web-script/pom.xml file and update it so it looks like this: 4.0.0 com.acme componentX-parent 1.0-SNAPSHOT componentX-web-script componentX-web-script JAR project http://maven.apache.org junit junit 3.8.1 test ${alfresco.groupId} alfresco-repository com.sun.mail javax.mail 1.5.3 provided

We also needed to add the alfresco-repository dependency as the Java Web Script controller uses Declarative Web Script classes. It does not have version specified as part of dependency definition, so we need to make sure it works anyway. 14.

Move the Dependency Management section from the AMP project to the Parent project. Open up the componentX-parent/pom.xml file and update it so it looks like this: 4.0.0 com.acme

98 Alfresco 5.1

Developer Guide

componentX-parent 1.0-SNAPSHOT componentX-repo Repository AMP parent This is the parent project for the multi-module componentX-repo Repository AMP project pom org.alfresco.maven alfresco-sdk-parent 2.2.0 componentX-repo componentX-web-script ${alfresco.groupId} alfresco-platform-distribution ${alfresco.version} pom import

It’s a good idea to move the Dependency Management section to the parent POM as you might have more JAR extensions added that needs Alfresco libraries, and then you want to be consitent with what version of these libraries you are using. The Repository AMP POM now looks like this (i.e. componentX-parent/componentX-repo/pom.xml) after removing the Java Mail dependency, moving Dependency Management, and putting in the Web Script JAR dependency: 4.0.0 com.acme componentX-parent 1.0-SNAPSHOT componentX-repo Repository AMP parent This is the parent project for the multi-module componentX-repo Repository AMP project pom org.alfresco.maven alfresco-sdk-parent 2.2.0 componentX-repo componentX-web-script ${alfresco.groupId}

Developer Guide 99

Developer Guide

alfresco-platform-distribution ${alfresco.version} pom import

We are now ready to build the project again. 15.

Build the Repository AMP parent project. You should see something like this in the logs: componentX-parent$ mvn clean install -DskipTests=true [INFO] Reactor Summary: [INFO] [INFO] componentX-repo Repository AMP parent .............. SUCCESS [ 0.556 s] [INFO] componentX-web-script JAR project .................. SUCCESS [ 2.662 s] [INFO] componentX-repo Repository AMP project ............. SUCCESS [ 4.688 s]

The Repository AMP now contains the following libraries:

Now it looks a bit better, we have split up the AMP code into two JARs and the Java Mail dependency is set to provided so no extra libraries are contained in the produced AMP. 16.

Run and try out the Hello World Web Script. To make sure this really works we need to try out the Web Script. Step into the AMP directory and do run.sh: componentX-parent$ cd componentX-repo/ componentX-parent/componentX-repo$ chmod +x run.sh componentX-parent/componentX-repo$ ./run.sh

You can test the Web Script as follows from a web browser:

100 Alfresco 5.1

Developer Guide

Remember, if you got the send email code in there, then it will try to send an email. And if you don't have an email server (SMTP) running locally, then the Web Script call will eventually time-out as in the following example: 2015-06-05 16:43:00,105 INFO [alfresco.util.OpenOfficeConnectionTester] [DefaultScheduler_Worker-1] The OpenOffice connection was reestablished. com.sun.mail.util.MailConnectException: Couldn't connect to host, port: brutor, 2525; timeout -1; nested exception is: java.net.ConnectException: Connection timed out

We have now seen how external libraries can be used in a Repository AMP project. We have also looked at how to turn the AMP project into a multi-module project to be able to split up the AMP code into multiple JAR extensions. Related Links Advanced Topics on page 86

Linking Standard Alfresco AMPs to an AIO project Some functionality of the Alfresco content management system is delivered as extra modules, such as Records Management (RM), Google Docs Integration, and Alfresco Office Services, whic provides SharePoint Protocol support. You can link such modules to an All-in-One (AIO) project. You should have completed Installing and Configuring software and generated an AIO project. You will learn how to link standard Alfresco AMPs to the AIO project so you can use the extra Alfresco functionality that they provide. Most of these modules are implemented with two AMPs. One for server side (Repository) customizations that should be added to the alfresco.war, and one with the custom UI functionality that should be added to the share.war. As an example we will add/link the Records Management (RM) module to the AIO project. It comes implemented in two AMPs. Linking the RM repository AMP to the alfresco.war. 1. Add the RM repository AMP dependency. In the IDE, open up the alfresco-extensions/acme-cms-poc/repo/pom.xml. Scroll down so you see the dependencies section:

Developer Guide 101

Developer Guide

What you need to do here is uncomment the alfresco-rm dependency, which brings in the RM Repository AMP. Note that dependency type is set to amp, this is because by default Maven dependencies are assumed to be JARs. 2. Overlaying the RM repository AMP on the alfresco.war. The RM repository AMP will not be automatically added to the alfresco.war by just adding the dependency. We need to add some configuration to the war plugin. Scroll further down in the alfresco-extensions/acme-cms-poc/repo/pom.xml file until you see the maven-war-plugin section:

102 Alfresco 5.1

Developer Guide

What you need to do here is uncomment the alfresco-rm overlay, which will overlay the RM repository AMP as the last operation to build the customized alfresco.war. Linking the RM Share AMP to the share.war. 3. Add the RM Share AMP dependency. In the IDE, open up the alfresco-extensions/acme-cms-poc/share/pom.xml. Scroll down so you see the dependencies section:

Developer Guide 103

Developer Guide

What you need to do here is uncomment the alfresco-rm-share dependency, which brings in the RM Share AMP. 4. Overlaying the RM Share AMP on the share.war. The RM Share AMP will not be automatically added to the share.war by just adding the dependency. We need to add some configuration to the war plugin. Scroll further down in the alfresco-extensions/acme-cms-poc/share/pom.xml file until you see the mavenwar-plugin section:

104 Alfresco 5.1

Developer Guide

What you need to do here is uncomment the alfresco-rm-share overlay, which will overlay the RM Share AMP as the last operation to build the customized share.war. Verify that the AIO project has been configured with the RM module. 5. Build and Run the AIO project. Use the acme-cms-poc/run.sh script to run Alfresco Tomcat with the customized WARs. 6. Check the logs for installation of RM module. 2015-05-07 10:30:17,004 [localhost-startStop-1] 2015-05-07 10:30:17,082 [localhost-startStop-1] version 2.3.

INFO [repo.module.ModuleServiceImpl] Found 2 module(s). INFO [repo.module.ModuleServiceImpl] Installing module 'org_alfresco_module_rm'

Developer Guide 105

Developer Guide

2015-05-07 10:30:18,560 INFO [repo.module.ModuleServiceImpl] [localhost-startStop-1] Upgrading module 'repo-amp' version 1.0.1505071028 (was 1.0.1505070918). .... INFO: Starting ProtocolHandler ["http-bio-8080"]

We can see here that version 2.3 of the RM module has been installed. 7. Check that the Site Type Records Management is available. Login to Share via http://localhost:8080/share and then create a new site. When you create the site select Records Management Site from the Type drop down. If this type is not available then something is not configured correctly, go back and verify that you have followed all the steps correctly. You have now seen how a standard Alfresco extension module, such as RM, can be brought into the All-in-One project. Other standard modules, such as SPP, can be added in a similar way. Note that some extension modules are implemented in only one AMP. For example, the SPP AMP in the above screen shots is implementing the SharePoint Protocol, which only touches the repository functionality, and so there is only an SPP dependency and overlay in the acme-cmspoc/repo/pom.xml project. Related Links Advanced Topics on page 86

Adding more custom AMPs to an AIO project When you generate an All-in-One project you get one Repository extension AMP (repo-amp) and one Share extension AMP (share-amp). These AMPs are just starting point AMPs, showing you how to create extension AMPs for the Alfresco WAR and Share WAR applications. When the project grows you are likely to want to add more extension modules for different types of functionality. The are many benefits to this: • It will be easier for multiple developers to work in parallel with different modules/ functionality as it is not all baked into one big AMP. • You can release and tag modules separately, which is really handy as you are not constantly working with SNAPSHOTS in your main AIO project. Meaning you can decide when you want to bring in new functionality. • You can very easily do a maintenance release for a specific bit of functionality. • It encourages re-use by not having all the extension functionality in one big AMP. There are two ways to go about this though: 1. Create new custom AMPs as separate projects outside the AIO project, this is the recommended approach as you get all the benefits listed above. 2. Create new custom AMPs as part of the AIO project, this does not give all of the above benefits. However, it is useful if you want to split up your extension code and structure it a bit, and you have only a very small team. It is also easier to implement as you don't need access to your own Maven Repository such as Nexus. It does however mean that you will be working with SNAPSHOT dependencies for all AMPs, so it will be difficult to decide when functionality should be included or not in the build. Basically, if the functionality exist in an AMP in the AIO project, it will be included in the build, whether it is complete or not. Related Links Advanced Topics on page 86 Creating new stand-alone custom AMPs and linking them to the AIO project on page 107 Create new custom AMPs as part of the AIO project on page 112

106 Alfresco 5.1

Developer Guide

Creating new stand-alone custom AMPs and linking them to the AIO project Use this information to create a new custom Repository AMP project and a new custom Share AMP project and then link those as dependencies in the AIO project. You should have completed Installing and Configuring software and generated an AIO project. You will learn how to create separate AMPs, that are not part of the AIO project, and then how to link those AMPs as dependencies in the AIO project. If you only need to add a Repository AMP, then skip the steps related to the Share AMP, and vice versa. Generating a new custom Repository AMP and linking it to the Alfresco.war. 1. Generate the custom Repository AMP. Follow instructions in the create Respository extension project (AMP) section. Give the new Repo AMP a unique artifact id that does not clash with any other ids or the one that is part of the AIO project (i.e. repo-amp). For this example I have used the id component-arepo. Use the same group id as for the rest of your project artifacts, I'm using com.acme. The AMP is stored in the alfresco-extensions/component-a-repo folder and is not part of the AIO build. 2. Build and release version 1.0.0 of the Repository AMP. (Optional) It is best to avoid SNAPSHOTS when this AMP is included in the All-in-One project. So, use the maven-release-plugin and release and tag the AMP so it is ready to be include in the main AIO project. Going through how to configure and set up the maven-release-plugin is out of scope for this article. 3. Add the custom Repository AMP Dependency In the IDE, open up the alfresco-extensions/acme-cms-poc/repo/pom.xml project file. Scroll down so you see the dependencies section. Then add a dependency to component-a-repo:

Developer Guide 107

Developer Guide

Note that dependency for the AMP uses the project.groupId, which is the same as what we used for the custom AMP, com.acme. If you skipped the build and release step (2), then use version 1.0-SNAPSHOT instead. 4. Overlaying the custom Repository AMP on the alfresco.war The Repository AMP will not be automatically added to the alfresco.war by just adding the dependency. We need to add some configuration to the war plugin. Scroll further down in the alfresco-extensions/acme-cms-poc/repo/pom.xml file until you see the mavenwar-plugin section. Then add a overlay for the component-a-repo:

108 Alfresco 5.1

Developer Guide

5. Run the AIO project and verify that the new repo module is recognized ... 2015-05-07 14:18:44,770 [localhost-startStop-1] 2015-05-07 14:18:44,791 [localhost-startStop-1] 1.0.0. 2015-05-07 14:18:44,808 [localhost-startStop-1] 1.0.1505071417. ....

INFO [repo.module.ModuleServiceImpl] Found 2 module(s). INFO [repo.module.ModuleServiceImpl] Installing module 'component-a-repo' version INFO [repo.module.ModuleServiceImpl] Installing module 'repo-amp' version

Generating a new custom Share AMP and adding it to the Share.war. 6. Generate the custom Share AMP. Follow instructions in the create Share extension project (AMP) section. Give the new Share AMP a unique artifact id that does not clash with any other ids or the one that is part of the AIO project (i.e. share-amp). For this example I have used the id component-a-

Developer Guide 109

Developer Guide

share. Use the same group id as for the rest of your project artifacts, I'm using com.acme. The AMP is stored in the alfresco-extensions/component-a-share folder and is not

part of the AIO build. 7. Build and release version 1.0.0 of the Share AMP. (Optional) It is best to avoid SNAPSHOTS when this AMP is included in the All-in-One project. So, use the maven-release-plugin and release and tag the AMP so it is ready to be include in the main AIO project. Going through how to configure and set up the maven-release-plugin is out of scope for this article. 8. Add the custom Share AMP Dependency. In the IDE, open up the alfresco-extensions/acme-cms-poc/share/pom.xml project file. Scroll down so you see the dependencies section. Then add a dependency to component-a-share:

110 Alfresco 5.1

Developer Guide

Note that dependency for the AMP uses the project.groupId, which is the same as what we used for the custom AMP, com.acme. If you skipped the build and release step (2), then use version 1.0-SNAPSHOT instead. 9. Overlaying the custom Share AMP on the share.war The Share AMP will not be automatically added to the share.war by just adding the dependency. We need to add some configuration to the war plugin. Scroll further down in the alfresco-extensions/acme-cms-poc/share/pom.xml file until you see the mavenwar-plugin section. Then add a overlay for the component-a-share:

10.

There is no logs indicating the AMPs that have been installed on the Alfresco Share web application, so the only way to test is to use whatever custom functionality it is implementing, and see if it works.

Developer Guide 111

Developer Guide

You have seen how to build AMP projects separately from the main AIO project, and then how you can incorporate those AMP projects in the main AIO project. Related Links Adding more custom AMPs to an AIO project on page 106

Create new custom AMPs as part of the AIO project Use this information to create a new custom Repository AMP project and a new custom Share AMP project and have them added as sub-projects of a multi module AIO project. This tutorial assumes that you completed Installing and Configuring software and generated an AIO project. You will learn how to create new custom AMPs and have them be part of a multi module AIO project. These AMPs will not be built separately but as part of the AIO project build. And they will be SNAPSHOT references in the AIO project. They will be very similar to the repo-amp and share-amp demo extension projects that comes with the AIO archetype. If you only need to add a Repository AMP, then skip the steps related to the Share AMP, and vice versa. Generating a new custom Repository AMP and linking it to the Alfresco.war. 1. Generate the custom Repository AMP as a sub-module to the AIO parent. Follow instructions in the create Respository extension project (AMP) section. Give the new Repo AMP a unique artifact id that does not clash with any other ids or the one that is part of the AIO project (i.e. repo-amp). For this example I have used the id component-a-repo. Use the same group id as for the rest of your project artifacts, I'm using com.acme. The AMP is generated and stored in the alfresco-extensions/acmecms-poc/component-a-repo folder and is going to be part of the AIO multi module project. 2. Update parent definition in the Repository AMP pom.xml and remove group and version definition By default the Repository AMP will be generated with the SDK Parent set. We need to change it to be the AIO project parent instead. You can grab a parent definition from one of the other sub-projects, such as the repo-amp project. The alfresco-extensions/acmecms-poc/component-a-repo/pom.xml file should now start like this: 4.0.0 component-a-repo component-a-repo Repository AMP project amp Manages the lifecycle of the component-a-repo Repository AMP (Alfresco Module Package) com.acme acme-cms-poc 1.0-SNAPSHOT ...

You should also remove and as these values will be picked up from the AIO parent. 3. Make sure the new Repository AMP is included as a module in the AIO parent pom.xml

112 Alfresco 5.1

Developer Guide

This should happen automatically when you generate the new project in a sub-directory to the parent AIO project directory. Open up the alfresco-extensions/acme-cms-poc/ pom.xml file and verify that the component-a-repo module is there: ... repo-amp share-amp repo solr-config share runner component-a-repo

4. Add the custom Repository AMP Dependency to Alfresco.war project In the IDE, open up the alfresco-extensions/acme-cms-poc/repo/pom.xml project file. Scroll down so you see the dependencies section. Then add a dependency to component-a-repo:

Developer Guide 113

Developer Guide

Note that the dependency for the AMP uses the project.groupId, which is what we used for the custom AMP, com.acme. It will also use whatever project.version is currently used. 5. Overlaying the custom Repository AMP on the alfresco.war The Repository AMP will not be automatically added to the alfresco.war by just adding the dependency. We need to add some configuration to the war plugin. Scroll further down in the alfresco-extensions/acme-cms-poc/repo/pom.xml file until you see the mavenwar-plugin section. Then add a overlay for the component-a-repo:

6. Enable the new custom Repository AMP for Rapid Application Development To be able to have hot-reloading work for the code that is going to be part of the new component-a-repo AMP, we need to update the virtual webapp context for the Repository webapp (i.e. for the alfresco.war webapp). In the IDE, open up the alfrescoextensions/acme-cms-poc/runner/tomcat/context-repo.xml file. Update the Resource section configuration with the new AMP's resource path:

114 Alfresco 5.1

Developer Guide

And update the Loader section configuration with the new AMP's classpaths:

The Tomcat context file located in the alfresco-extensions/acme-cms-poc/ component-a-repo/tomcat directory is obsolete when the AMP is contained within an AIO project, it is only used when the AMP is run stand-alone, and it can be deleted. 7. Start it up and verify that the new AMP is installed ... 2015-05-08 13:40:37,688 INFO [repo.module.ModuleServiceImpl] [localhost-startStop-1] Found 2 module(s). 2015-05-08 13:40:37,713 INFO [repo.module.ModuleServiceImpl] [localhost-startStop-1] Upgrading module 'component-a-repo' version 1.0.1505081338 (was 1.0.1505071304). 2015-05-08 13:40:37,746 INFO [repo.module.ModuleServiceImpl] [localhost-startStop-1] Upgrading module 'repo-amp' version 1.0.1505081338 (was 1.0.1505081106). ...

Generating a new custom Share AMP and and linking it to the Share.war. 8. Generate the custom Share AMP as a sub-module to the AIO parent. Follow instructions in the create Share extension project (AMP) section. Give the new Share AMP a unique artifact id that does not clash with any other ids or the one that is part of the AIO project (i.e. share-amp). For this example I have used the id component-ashare. Use the same group id as for the rest of your project artifacts, I'm using com.acme. The AMP is generated and stored in the alfresco-extensions/acme-cms-poc/ component-a-share folder and is going to be part of the AIO multi module project. 9. Update parent definition in the Share AMP pom.xml and remove group and version definition By default the Share AMP will be generated with the SDK Parent set. We need to change it to be the AIO project parent instead. You can grab a parent defintion from one of the other sub-projects, such as the share-amp project. The alfresco-extensions/acmecms-poc/component-a-share/pom.xml file should now start like this: 4.0.0 component-a-share component-a-share AMP project amp Manages the lifecycle of the component-a-share AMP (Alfresco Module Package)

Developer Guide 115

Developer Guide

com.acme acme-cms-poc 1.0-SNAPSHOT ...

You should also remove and as these values will be picked up from the AIO parent. 10.

Make sure the new Share AMP is included as a module in the AIO parent pom.xml This should happen automatically when you generate the new project in a sub-directory to the parent AIO project directory. Open up the alfresco-extensions/acme-cms-poc/ pom.xml file and verify that the component-a-share module is there: ... repo-amp share-amp repo solr-config share runner component-a-repo component-a-share

11.

Add the custom Share AMP Dependency. In the IDE, open up the alfresco-extensions/acme-cms-poc/share/pom.xml project file. Scroll down so you see the dependencies section. Then add a dependency to component-a-share:

116 Alfresco 5.1

Developer Guide

Note that the dependency for the AMP uses the project.groupId, which is what we used for the custom AMP, com.acme. It will also use whatever project.version is currently used. 12.

Overlaying the custom Share AMP on the share.war The Share AMP will not be automatically added to the share.war by just adding the dependency. We need to add some configuration to the war plugin. Scroll further down in the alfresco-extensions/acme-cms-poc/share/pom.xml file until you see the mavenwar-plugin section. Then add a overlay for the component-a-share:

Developer Guide 117

Developer Guide

13.

Enable the new custom Share AMP for Rapid Application Development To be able to have hot-reloading work for the code that is going to be part of the new component-a-share AMP, we need to update the virtual webapp context for the Share webapp (i.e. for the share.war webapp). Also, if we don't do this any web resources such as CSS, Images, JS etc located under /web in the AMP will not be available when we use the run profile (this is because during hot reloading we only want them in one place, our project). In the IDE, open up the alfresco-extensions/acme-cms-poc/runner/tomcat/ context-share.xml file. Update the Resource section configuration with the new AMP's resource path:

118 Alfresco 5.1

Developer Guide

And update the Loader section configuration with the new AMP's classpaths:

The Tomcat context file located in the alfresco-extensions/acme-cms-poc/ component-a-share/tomcat directory is obsolete when the AMP is contained within an AIO project, it is only used when the AMP is run stand-alone, and it can be deleted. 14.

There is no logs indicating the AMPs that have been installed on the Alfresco Share web application, so the only way to test is to use whatever custom functionality it is implementing, and see if it works.

You have seen how to create new custom AMP projects that should be part of an All-in-One (AIO) project. Related Links Adding more custom AMPs to an AIO project on page 106

Deploying All-in-One (AIO) WARs to external environments Use this information to deploy the WARs that are produced by the All-In-One (AIO) project to an external environment, such as QA, UAT, and PRODUCTION. You should have completed Installing and Configuring software and generated an AIO project. Building an AIO project generates the customized alfresco.war and share.war for use in an Alfresco installation. However, by default the alfresco.war will be configured with an alfresco-global.properties file that assumes it will be deployed in a local environment, with the alf_data directory in the build project and the use of the flat file H2 database. It is in fact assuming that we will run the environment from Maven (i.e. mvn clean install -Prun). Therefore, if we take the WAR files that are produced during a mvn clean install build and deploy them to an external Alfresco installation, it will not work. This 'local' configuration is managed by a so called environment configuration. The SDK supports multiple environment configurations and this gives us the opportunity to manage configurations for multiple Alfresco environments. This also means that the produced WAR files will contain environment specific configuration, which might not be wanted in all situations. We can prevent this with the use of a specific property during build. Excluding the environment configuration from the produced Alfresco Repository WAR file. 1. Build with the app.properties.include property set to "none". The app.properties.include is normally set to **, which will include all the files under src/main/properties/${env} (e.g. alfresco-global.properties). If we set this property to none it will not match any files. Note that it does not work to set this property to an empty string, and the Maven plug-in that is used does not have a skip configuration option: all-in-one$ mvn clean install -Dapp.properties.include=none

Developer Guide 119

Developer Guide

2. Copy the produced WAR files to the Alfresco installation When the AIO project has been built without environment specific configuration we can copy the WAR files to an Alfresco installation: all-in-one$ cd repo/target/ all-in-one/repo/target$ mv repo.war alfresco.war all-in-one/repo/target$ cp alfresco.war /opt/alfresco50d/tomcat/webapps/ all-in-one/repo/target$ cd ../../share/target/ all-in-one/share/target$ cp share.war /opt/alfresco50d/tomcat/webapps/ all-in-one/share/target$ cd /opt/alfresco50dTest/ alfresco50d$ cd tomcat/webapps alfresco50d/tomcat/webapps$ rm -rf alfresco/ share/

Note that we need to remove the exploded WAR directories for the new WARs to be picked up and deployed. Also, the Alfresco Repository WAR is generated with the repo.war name so we need to change it to alfresco.war before copying it over to the Alfresco installation. 3. Restart Alfresco Tomcat The new WARs are now in place so restart Tomcat to have them deployed: alfresco50d$ ./alfresco.sh restart tomcat

Including environment specific configuration in the produced Alfresco Repository WAR file. 4. Create a new environment directory This should be done in the all-in-one/repo/src/main/properties directory, which already contains the local directory representing the local environment. Name the new directory after the environment you are deploying to, such as for example uat (i.e. User Acceptance Testing): all-in-one/repo/src/main/properties$ mkdir uat

5. Copy the alfresco-global.properties file from the external UAT environment to the environment directory. You will find the environment specific file located in the alfresco/tomcat/shared/ classes directory from where it can be copied to the build project. At this point you should see something like this under the repo project: all-in-one/repo/src/main$ tree . ### properties # ### local # # ### alfresco-global.properties # ### uat # ### alfresco-global.properties ### resources ### alfresco ### extension ### dev-log4j.properties

So we got the local environment configuration that will point to a development alf_data directory and the H2 database. We then have a new environment configuration called uat that contains an alfresco-global.properties file that has been copied from that environment's alfresco/tomcat/shared/classes directory. Looking in the uat environment's properties file we will see something like this (or whatever configuration we have done for the UAT environment): ############################### ## Common Alfresco Properties # ############################### dir.root=/opt/alfresco/alf_data

120 Alfresco 5.1

Developer Guide

alfresco.context=alfresco alfresco.host=127.0.0.1 alfresco.port=8080 alfresco.protocol=http share.context=share share.host=127.0.0.1 share.port=8080 share.protocol=http ### database connection properties ### db.driver=org.postgresql.Driver db.username=alfresco db.password=admin db.name=alfresco db.url=jdbc:postgresql://localhost:5432/${db.name} # Note: your database must also be able to accept at least this many connections. Please see your database documentation for instructions on how to configure this. db.pool.max=275 db.pool.validate.query=SELECT 1 ...

6. Build WARs to include the UAT environment specific configuration. We can now activate the UAT environment configuration by specifying the name on the command line (it defaults to local): all-in-one$ mvn clean install -DskipTests=true -Denv=uat

The alfresco-global.properties configuration file for the uat environment will end up in the tomcat/webapps/alfresco/WEB-INF/classes directory of the final alfresco.war. It will take precedence over the tomcat/shared/classes/alfrescoglobal.properties file. Note here also that we need to skip Unit tests while doing this build as they require a local context to be running, which is not possible when we change environment configuration. 7. Copy the produced WAR files to the Alfresco installation When the AIO project has been built with the UAT environment specific configuration we can copy the WAR files to this Alfresco installation: all-in-one$ cd repo/target/ all-in-one/repo/target$ mv repo.war alfresco.war all-in-one/repo/target$ cp alfresco.war /opt/alfresco50d/tomcat/webapps/ all-in-one/repo/target$ cd ../../share/target/ all-in-one/share/target$ cp share.war /opt/alfresco50d/tomcat/webapps/ all-in-one/share/target$ cd /opt/alfresco50dTest/ alfresco50d$ cd tomcat/webapps alfresco50d/tomcat/webapps$ rm -rf alfresco/ share/

Note that we need to remove the exploded WAR directories for the new WARs to be picked up and deployed. Also, the Alfresco Repository WAR is generated with the repo.war name so we need to change it to alfresco.war before copying it over to the Alfresco installation. 8. Restart Alfresco Tomcat The new WARs are now in place so restart Tomcat to have them deployed: alfresco50d$ ./alfresco.sh restart tomcat

This article has shown how it is possible to generate WAR files without any environment specific configuration, making them deployable to any environment. We have also covered how to set up a new custom environment configuration, and how to have it included in the final WAR, making it deployable only to a specific Alfresco server.

Developer Guide 121

Developer Guide

Related Links Advanced Topics on page 86

Upgrading This information walks through how to upgrade your project to use a newer version of Alfresco. It also takes you through the process of upgrading your project to use a newer version of the SDK. There are two areas: • Upgrading the Alfresco Product version • Upgrading the Alfresco SDK version Related Links Alfresco SDK 2.2.0 on page 16 Upgrading Alfresco Version for an extension project on page 122 Upgrading SDK version for an extension project on page 124

Upgrading Alfresco Version for an extension project When you have been working with your extension project for a while it is highly likely that there have been some new releases of the Alfresco software. These releases will have new functionality that you might want to take advantage of in your project. It might also be that you are starting to work with this SDK version a while after it has been released, and latest Alfresco version is now newer than what is default in the SDK. Use this information to upgrade your SDK project to use the newest Alfresco version. This task assumes that you have an SDK project to work with, see creating a project. You will learn how to set a new version in all the different kinds of SDK project types. Upgrading Alfresco version for a Repository AMP project. 1. Set new version. In the IDE, open up the Repository AMP project that you are working on. Then open the project file for it, for example alfresco-extensions/component-a-repo/pom.xml. Scroll down so you see the properties section: 5.0.e

What you need to do here is uncomment the alfresco.version property, and then update the version to the required latest version. In this case we are upgrading to a newer Community Edition (default is 5.0.d). It would be the same procedure to upgrade to a newer Enterprise version. 2. Clean metadata and content. After setting a newer Alfresco version you will need to clean out current database (with metadata), content files, and indexes. It currently does not work to do an incremental upgrade with the SDK and the H2 database. You can clean the DB and conten files by running the following command: alfresco-extensions/component-a-repo/mvn clean -Ppurge

Upgrading Alfresco version for a Share AMP project.

122 Alfresco 5.1

Developer Guide

3. Set new version. In the IDE, open up the Share AMP project that you are working on. Then open the project file for it, for example alfresco-extensions/component-a-share/pom.xml. Scroll down so you see the properties section: 5.0.e ...

What you need to do here is uncomment the alfresco.version property, and then update the version to the required latest version. In this case we are upgrading to a newer Community Edition (default is 5.0.d). It would be the same procedure to upgrade to a newer Enterprise version. 4. Clean metadata and content When upgrading the Alfresco Share AMP it is not necessary to clean out a database or clean content because these are related to the Alfresco Repository application (alfresco.war) and not the Share Application (share.war). Upgrading Alfresco version for an All-in-One (AIO) project. 5. Set new version. In the IDE, open up the All-in-One project that you are working on. Then open the project file for it, for example alfresco-extensions/all-in-one/pom.xml. Scroll down so you see the properties section: 5.0.e 2.3.b

What you need to do here is uncomment the alfresco.version property, and then update the version to the required latest version. In this case we are upgrading to a newer Community edition (default is 5.0.d). It would be the same procedure to upgrade to a newer Enterprise edition. Note also that in this case I'm using the Records Management module and I am updating the version for it at the same time by uncommenting the alfresco.rm.version property and setting new version. 6. Clean metadata and content After setting a newer Alfresco version you will need to clean out current database (with metadata), content files, and indexes. It currently does not work to do an incremental upgrade with the SDK and the H2 database. You can clean the DB and conten files by running the following command: alfresco-extensions/component-a-repo/mvn clean -Ppurge

You have now seen how to upgrade the SDK project's Alfresco version and how to clean DB and content before starting with the new version. Related Links Upgrading on page 122

Developer Guide 123

Developer Guide

Upgrading SDK version for an extension project This information describes how to upgrade the SDK version that is used by your extension project. These instructions include information about how to upgrade projects generated from each one of the artifacts. Make sure you are following upgrade instructions for the correct project type and "From version -> To version". Make sure you have made a complete backup of your project before you start the upgrade process! Related Links Upgrading on page 122 What changes are allowed in an SDK release? on page 124 Upgrading SDK version from 2.0.0 to 2.1.0 on page 124 Upgrading SDK version from 2.1.0 to 2.1.1 on page 136 Upgrading SDK version from 2.1.1 to 2.2.0 on page 140

What changes are allowed in an SDK release? The following describes the kind of changes you can expect (are allowed) in major, minor, and patch releases. A 3 digit versioning scheme is used, major.minor.patch (e.g. 2.1.0). The following is a list of changes that can go into each one of these releases: 1. major a.

Backward incompatible changes (e.g. changes in the archetype project structure, functional changes in archetypes POMs, functional changes in existing profiles)

b.

Changes in the artifact naming

2. minor Cannot change existing behaviors (e.g. existing profiles semantics, build lifecycle, archetype structure). a.

New features (e.g. new alfresco-sdk-parent, new archetype profiles, new properties)

b.

New artifacts

3. patch Ideally no changes to the code of the archetypes. a.

Bug Fixes

b.

Limited changes to SDK parent and Alfresco Plugin

Note that in addition to this there can be beta releases to give early access to features. Related Links Upgrading SDK version for an extension project on page 124

Upgrading SDK version from 2.0.0 to 2.1.0 This section contains instructions for how to upgrade an extension project from using SDK version 2.0.0 to using SDK version 2.1.0. These instructions include information about how to upgrade projects generated from each one of the Maven artifacts. Make sure you are following upgrade instructions for the correct project type. Default Alfresco versions for SDK 2.0.0 is Community 5.0.c and Enterprise 5.0. After upgrading to SDK 2.1.0 the default Alfresco versions will be Community 5.0.d and Enterprise 5.0.1. Make sure you have made a complete backup of your project before you start the upgrade process!

124 Alfresco 5.1

Developer Guide

Related Links Upgrading SDK version for an extension project on page 124 Upgrading a Repository AMP project from SDK 2.0.0 to 2.1.0 on page 125 Upgrading a Share AMP project from SDK 2.0.0 to 2.1.0 on page 127 Upgrading an All-in-One (AIO) project from SDK 2.0.0 to 2.1.0 on page 129

Upgrading a Repository AMP project from SDK 2.0.0 to 2.1.0 These instructions will walk through what is needed when upgrading a Repository AMP project from using SDK version 2.0.0 to using SDK version 2.1.0. There are multiple ways to go about an SDK upgrade. These instructions assume that you have a Repository AMP project where the source code is managed by a Software Configuration Management (SCM) system such as Git or Subversion. And you cannot just through away the history of this project, you need to upgrade "in-place". On the other hand, if your project is small, and you don't mind starting with a new project in the SCM, it might be easier to just generate a new project from the Repository AMP 2.1.0 SDK archetype and move the code and other changes over to it from the SDK 2.0.0 project, but this method is not covered in this article. In the following instructions the REPO_AMP_PROJECT_PATH variable denotes the path to where you have your Repository AMP project folder. So, for example, if your Repository AMP project was generated in the C:\alfresco-extensions\acme-repo-amp directory, then this directory path is the value of this variable. Make sure you have made a complete backup of your project before you start the upgrade process! 1. Setting the SDK Version to 2.1.0. In the IDE, open up the {REPO_AMP_PROJECT_PATH}/pom.xml project file. Scroll down so you see the parent section. Then update it to look as follows: org.alfresco.maven alfresco-sdk-parent 2.1.0

2. Remove the property used to specify the webapp path for Alfresco Repository web application. In the project file {REPO_AMP_PROJECT_PATH}/pom.xml scroll down to the properties section. Then remove the property called alfresco.client.contextPath. This property is already set to /alfresco in the SDK parent POM so no need to set it here. 3. Add the amp-to-war profile with rad dependency. In the IDE, open up the {REPO_AMP_PROJECT_PATH}/pom.xml project file. Scroll down so you see the profiles section. Then add the following profile to it: amp-to-war org.alfresco.maven alfresco-rad ${maven.alfresco.version}

Developer Guide 125

Developer Guide



4. Update the Tomcat virtual webapp context file. Open the {REPO_AMP_PROJECT_PATH}/tomcat/context.xml file. Change it to look like this for best RAD experience:



5. Replace run scripts. Version 2.1.0 of the SDK have changes to the Linux run scripts and have new run scripts for Windows. So it make sense to take the new scripts from a newly generated 2.1.0 Repository AMP project and replace the 2.0.0 scripts with them. So follow these instructions to generate a Repository AMP project based on the 2.1.0 archetype. Then just copy over the {newly generated 2.1.0 Repo AMP}/run.* scripts to the {REPO_AMP_PROJECT_PATH} directory, overwriting the run.sh script. Your Repository AMP project should now be fully updated to use the 2.1.0 version of the SDK. Related Links Upgrading SDK version from 2.0.0 to 2.1.0 on page 124

126 Alfresco 5.1

Developer Guide

Upgrading a Share AMP project from SDK 2.0.0 to 2.1.0 These instructions will walk through what is needed when upgrading a Share AMP project from using SDK version 2.0.0 to using SDK version 2.1.0. There are multiple ways to go about an SDK upgrade. These instructions assume that you have a Share AMP project where the source code is managed by a Software Configuration Management (SCM) system such as Git or Subversion. And you cannot just through away the history of this project, you need to upgrade "in-place". On the other hand, if your project is small, and you don't mind starting with a new project in the SCM, it might be easier to just generate a new project from the Share AMP 2.1.0 SDK archetype and move the code and other changes over to it from the SDK 2.0.0 project, but this method is not covered in this article. In the following instructions the SHARE_AMP_PROJECT_PATH variable denotes the path to where you have your Share AMP project folder. So, for example, if your Share AMP project was generated in the C:\alfresco-extensions\acme-share-amp directory, then this directory path is the value of this variable. Make sure you have made a complete backup of your project before you start the upgrade process! 1. Setting the SDK Version to 2.1.0. In the IDE, open up the {SHARE_AMP_PROJECT_PATH}/pom.xml project file. Scroll down so you see the parent section. Then update it to look as follows: org.alfresco.maven alfresco-sdk-parent 2.1.0

2. Remove the property used to specify the webapp path for the Alfresco Share web application. In the project file {SHARE_AMP_PROJECT_PATH}/pom.xml scroll down to the properties section. Then remove the property called alfresco.client.contextPath. This property is now called share.client.contextPath, and it is already set to /share in the SDK parent POM, so no need to set it here. 3. Update the name of the property specifying Share Webapp aritifact ID. In the project file {SHARE_AMP_PROJECT_PATH}/pom.xml scroll down to the properties section. Then change the name of the property called alfresco.client.war to app.amp.client.war.artifactId. 4. Add a build section to enable the JS Compression plugin. In the same project file {SHARE_AMP_PROJECT_PATH}/pom.xml scroll down to the dependencies end tag. Then add the following build section after it with the yuicompressor-maven-plugin to enable JS compression: . . . net.alchim31.maven yuicompressor-maven-plugin

5. Update share-config-custom.xml to enable better RAD.

Developer Guide 127

Developer Guide

Open the {SHARE_AMP_PROJECT_PATH}/src/test/resources/alfresco/webextension/share-config-custom.xml file and update the web-framework configuration so it looks like this: production