Create a Data Services application for the Experience Server that returns data

The Data Services application that is developed in this topic consists of a Java class named EchoService. This class exposes a method named sayHello that returns the string value that is passed to it. The Java class is placed into an Experience Services package by using Maven, which is an open source build tool. Once bundled into a package, the package is deployed to the Experience Server.

The following illustration displays the Flex client application that is created. This client application calls the sayHello method that is exposed by the EchoService class.

Note: To quickly get you up and running with the Adobe Digital Enterprise Platform, this section creates a simple server-side destination that contains a single operation. A Flex client application is also created that invokes the operation.

Summary of Steps

To create a Data Services application for the Experience Server that returns data, perform the following tasks:

  1. Extract SDK files from the Experience Server.

  2. Set up Maven 3 in your development environment.

  3. Create the Java server-side class that returns a string value.

  4. Build the Experience Services package that contains the Java server-side class.

  5. Deploy the Experience Services package to the Experience Server.

  6. Define the server-side destination that lets client applications call methods located in the server-side class.

  7. Create the client application by using Flash Builder.

Retrieving SDK files from the Experience Server

The first step to create a Data Services application is to extract SDK files from the Experience Server. For example, you extract the Data Services JAR file that you add to your Java server project's classpath.

The Experience Server contains the Package Manager that lets you view deployed Experience Services packages. Using the Package Manager, you can download deployed packages such as dataservices-sdk-pkg.zip to a local folder and extract its contents. You can select any of the deployed packages, as shown in the following illustration of the Package Manager.

Note: You also use the Package Manager to deploy packages. (See Deploy the Experience Services package to the Experience Server.)

You use the Package Manager to download the following SDK files:

  • Server-side JAR file

  • Client-side SWC files

  • The template application

Note: Ensure that you retrieve the Data Services SDK and samples packages by using Package Share. These packages contain files, such as the template application that you require to create a package that contains the Java class. For information about retrieving these packages by using Package Share, see Installing Samples and SDK Packages located in Getting Started for Developers.

To download a package by using the Package Manager

  1. To view the Adobe Digital Enterprise Platform welcome page, enter the URL http://[host name]:[port] into a web browser. For example, http://localhost:4502.

  2. Enter a valid user name and password. The default value for both values is admin.

  3. Click Packages.

  4. Select the name of the package that corresponds to the ZIP file you want to download.

  5. From the menu that appears, select Download.

  6. Save the ZIP file to a folder on your local file system.

  7. Extract the contents of the ZIP file.

Retrieving the Data Services JAR file

The Data Services JAR file that you add to your Java project's class path is named dataservices-bundle.jar. This JAR file serves two purposes. First you have to add it to your Java project when your Java project uses Data Services APIs such as flex.data.assemblers.AbstractAssembler.

Second, you add the dataservices-bundle.jar to the lib folder of the template application that you use to create the package. For information, see Building the Experience Services package that contains the EchoService class.

This file is located in dataservices-sdk-pkg.zip. After you download and extract the contents of this ZIP file, you can locate the dataservices-bundle.jar in the following location:

[ZIP location]\dataservices-sdk-pkg\jcr_root\etc\aep\sdks\riaservices\dataservices\4.5.0\java

Where [ZIP location] is the location in which you downloaded the dataservices-sdk-pkg.zip file.

Note: You can view the dataservices-bundle.jar file in the following path by using CRXLite: /libs/dataservices/bundles/install. For information about using CRXLite, see Defining the server destination for the echo service.

Retrieving the client-side SWC files

You use the Package Manager to retrieve client-side SWC files. You add these SWC files to your client application created by using Flash Builder. (See Creating a Flash Builder client project for the Echo service.)

Note: If you use the modeler plug-in and create an Adobe Digital Enterprise Platform project, you do not have to add client SWC files to the project. They are added by Flash Builder. To learn how to build a Flash Builder client application without modeler plug-in, see Create a Flash Builder client project.

To retrieve the SWC files, download dataservices-sdk-pkg.zip. This ZIP file contains the following SWC files:

  • fds.swc

  • playerfds.swc

  • fds_rb.swc

After you extract the contents of dataservices-sdk-pkg.zip, you can locate the fds.swc file in the following location:

[ZIP location]\dataservices-sdk-pkg\jcr_root\etc\aep\sdks\riaservices\dataservices\4.5.0\flex\frameworks\libs

Where [ZIP location] is the location in which you downloaded dataservices-sdk-pkg.zip.

You can locate the playerfds.swc file in the following location:

[ZIP location]\dataservices-sdk-pkg\jcr_root\etc\aep\sdks\riaservices\dataservices\4.5.0\flex\frameworks\libs\player

You can locate the fds_rb.swc file in the following location:

[ZIP location]\dataservices-sdk-pkg\jcr_root\etc\aep\sdks\riaservices\dataservices\4.5.0\flex\frameworks\locale\en_US

Note: You can view these SWC files in the following path by using CRXLite: /libs/dataservices/flex/lib. For information about using CRXLite, see Defining the server destination for the echo service.

Retrieving the template application

You retrieve the template application by using the Package Manager. The template application is packaged as a ZIP file named dataservices-example-app-template.zip. You use the template application to place files, such as Java classes and Flex applications, into an Experience Services package. For information, see Building the Experience Services package that contains the EchoService class.

The template application is located within the dataservices-sdk-pkg.zip file. After you download and extract the contents of this ZIP file, you can locate the dataservices-example-app-template.zip file in the following location:

[ZIP location]\dataservices-sdk-pkg-4.5.0-0050\jcr_root\etc\aep\sdks\riaservices\dataservices\4.5.0

Setting up Maven in your development environment

You use Maven to build an Experience Services package that consists of server-side classes and other files that a service uses. You can download Maven 3 from the following URL:

http://maven.apache.org/download.html

After you download and extract Maven, create an environment variable named M3_HOME. Assign the Maven install location to this environment variable. For example, C:\DataServices\common\tools\apache-maven-3.0.3.

When you use Maven to build an Experience Services package, you reference the M3_HOME variable.

Note: As part of setting up and using Maven, you typically setup a Maven repository. A Maven repository stores files that the Maven build process uses. You do not have to add Adobe JAR files to your Maven repository to build a package. For more information about Maven repositories, see Introduction to Repositories.

Creating the Java server-side class for the Echo service

You create server-side Java classes in a Java IDE such as Eclipse. For simplicity, the Experience Services package created in this section consists of a single class named EchoService. This class contains a method named sayHello that returns a string value, as shown in the following code example.

package com.adobe.myexample; 
 
public class EchoService { 
     
    public String sayHello(String val){ 
         
        return "Adobe Digital Enterprise Platform says: " +val ; 
    } 
}

Normally you add the dataservices-bundle.jar to your Java project’s class path. The reason is because application logic in the server-side classes typically use Data Services APIs. However, EchoService does not use Data Services APIs. Therefore you do not have to add dataservices-bundle-4.5.0.jar to your Java project’s class path to compile EchoService.

Note: Notice that EchoService is located in a package named com.adobe.myexample. You reference the fully qualified class name when you define a destination in a Data Services XML configuration file. For information, see Defining the server destination for the echo service.

Building the Experience Services package that contains the EchoService class

After you create the EchoService class, you place it into an Experience Services package by using both Maven and the dataservices-example-app-template application. The Experience Services package that is created is a ZIP file. The template application was retrieved by using the Package Manager. For information, see Retrieving the template application.

Extract the dataservices-example-app-template.zip file into a local folder. The following illustration shows the folder strucuture of the template application.

The following table explains the folder structure.

Folder

Description

lib

Place the dataservices-bundle.jar that you downloaded from the Adobe Digital Enterprise Platform into this folder.

For information about retrieving this JAR file, see Retrieving the Data Services JAR file.

package

Contains a Project Object Model (POM) file that you can modify prior to building the package. A POM file is an XML file that specifies how to build the package. For information about POM files, see http://maven.apache.org/pom.html.

This folder contains a sub-folder named jcr_root that represents the root of the Experience Server repository. When you need to package files other than Java source files, you place them in a sub-folder of jcr_root . For example, you can package data model files by placing project files under jcr_root. For information, see Create an Experience Services package that contains model-driven application files.

For this section, you do not have to place files under jcr_root.

The package/target folder is created after you run Maven. The ZIP file that represents the package that you deploy to the server is placed in the target folder.

sourceCode

Contains source files that are used to build the package. Place the Java source files under the sourceCode\src\main\java folder.

Under the java folder, create a folder structure that reflects the Java package structure. For example, the folder structure to create the package developed in this section is sourceCode\src\main\java\com\adobe\myexample.

To place the application files in the template application (Required)

  1. Place the dataservices-bundle.jar that you downloaded from the Experience Server into the template application’s lib folder.

  2. Under the sourceCode\src\main\java folder, create a folder structure that reflects the Java package structure. The folder structure to create the package developed in this section is sourceCode\src\main\java\com\adobe\myexample.

  3. Place the following EchoService.java file in the myexample folder.

Specify the Java package to export (Required)

You specify the Java package to export by modifying the pom.xml file that is located in the sourceCode folder. If you do not specify a Java package in the pom.xml file, then an exception is thrown when a client application calls an operation that is located in your package.

To specify a Java package, specify the Java package name in the Export-Package element, as shown in the following example.

<Export-Package> 
    com.adobe.myexample 
</Export-Package>

In this example, com.adobe.myexample represents the Java package to which the EchoService class belongs. If there is more than one package, you can use a comma to separate each package.

Specifying the name of the Experience Services package (Optional)

The package folder contains XML files named pom.xml and assembly.xml that you can modify to determine the package name. The pom.xml file contains a parent element that specifies build details such as the version of the package. Under the parent element, you can modify, for example, the version attribute to specify the version of the package.

Note: The assembly.xml file is used by the Maven "assembly" plugin. This plugin is referenced in the pom.xml file. (See http://maven.apache.org/plugins/maven-assembly-plugin/.)

The following XML represents elements in the pom.xml file.

<?xml version="1.0"?> 
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> 
    <modelVersion>4.0.0</modelVersion> 
    <!-- ====================================================================== --> 
    <!-- P A R E N T  P R O J E C T  D E S C R I P T I O N                      --> 
    <!-- ====================================================================== --> 
    <parent> 
        <groupId>com.adobe.dataservices.example.app</groupId> 
        <artifactId>dataservices-example-app-parent</artifactId> 
        <version>1.0-SNAPSHOT</version> 
        <relativePath>../parent/pom.xml</relativePath> 
    </parent> 
 
    <!-- ====================================================================== --> 
    <!-- P R O J E C T  D E S C R I P T I O N                                   --> 
    <!-- ====================================================================== --> 
    <groupId>com.adobe.dataservices.example.app</groupId> 
    <artifactId>dataservices-example-app-package</artifactId> 
    <packaging>pom</packaging> 
    <name>Data Services Example App</name> 
 
    <properties> 
        <content.dir>${project.build.directory}/assembly</content.dir> 
        <jcr.root.dir>${project.build.directory}/assembly/jcr_root</jcr.root.dir> 
    </properties>

Another element that you can modify is artifactId. In the previous example, notice that the value of this element is dataservices-example-app-package.

The assembly.xml file also contains an XML element named id that specifies the package name. The following XML represents the assembly.xml.

<!-- 
    This file defines how to create the ZIP file. 
--> 
<assembly> 
    <id>mypackage</id> 
    <includeBaseDirectory>false</includeBaseDirectory> 
    <formats> 
        <format>zip</format> 
    </formats> 
    <fileSets> 
        <fileSet> 
            <outputDirectory>.</outputDirectory> 
            <directory>target/assembly</directory> 
        </fileSet> 
    </fileSets> 
</assembly>

Maven produces a package by using values in both the pom.xml file and the assembly.xml file. The default name of the package is dataservices-example-app-package-1.0-SNAPSHOT-mypackage.zip. The dataservices-example-app-package-1.0-SNAPSHOT value is specified in the pom.xml file. Likewise, mypackage is specified in the assembly.xml file.

Ensure that each package that you deploy to the Experience Server has a unique name. If you attempt to deploy a package that has the same name of a deployed package, then a javax.jcr.ItemExistsException is thrown.

Specifying package files to uninstall (Optional)

You use the filter.xml file to specify the package's files and folders to uninstall when you uninstall the package. If you do not specify a file or folder in the filter.xml file, then it is not uninstalled when the package is uninstalled. For example, you can specify a destination XML configuration to ensure that it is uninstalled when the package is uninstalled.

Experience Server uses the filter.xml file to take a snapshot of the contents of the files and folders listed before it installs the package. It restores the snapshot when the package is uninstalled. That is, Experience Server reverts back to the state that it was in when the snapshot was taken.

The following XML represents the filer.xml file.

<?xml version="1.0" encoding="UTF-8"?> 
<!-- 
    The filters define the paths that are *removed* when the package is un-installed.  You should update this to include any files or folders you install. 
--> 
<workspaceFilter version="1.0"> 
    <filter root="/libs/dataservices-example-app"/> 
    <filter root="/apps/dataservices-example-app"/> 
    <!-- This will ensure our destination config is removed when we are un-installed --> 
    <filter root="/etc/aep/config/dataservices/destinations/remoting"> 
        <include pattern="/etc/aep/config/dataservices/destinations/remoting/com.sample.empty.xml" /> 
    </filter> 
</workspaceFilter>

Replace com.sample.empty.xml with the name of the file that you want to uninstall when the package is uninstalled. For example, to uninstall the remoting XML configuration file that is created in this section, specify com.adobe.myexample.xml.

You can locate the filter.xml file in the template application' package folder:

package\META-INF\vault

Running Maven to create the package (Required)

You can run Maven in the Command Prompt to build the package. Maven builds a package as a ZIP file and places it in the template application’s package/target folder. If the build is successful, you will see a message in the Command Prompt similiar to the following message:

[INFO] Reactor Summary: 
[INFO] 
[INFO] Data Services Example - Parent .................... SUCCESS [0.203s] 
[INFO] Data Services Example - OSGi Bundle ............... SUCCESS [22.620s] 
[INFO] Data Services Example - Package ................... SUCCESS [1.125s] 
[INFO] ------------------------------------------------------------------------ 
[INFO] BUILD SUCCESS 
[INFO] ------------------------------------------------------------------------ 
[INFO] Total time: 24.398s 
[INFO] Finished at: Wed Aug 03 18:58:38 EDT 2011 
[INFO] Final Memory: 18M/232M

To create the package by running Maven

  1. Start the Command Prompt.

  2. Change the directory to the location of dataservices-example-app-template.

  3. Enter the following command: %M3_HOME%\bin\mvn clean install.

Note: Ensure that you have properly setup Maven and the environment variables before building the package. (See Setting up Maven in your development environment.)

Deploy the Experience Services package to the Experience Server

You deploy a package to the Experience Server by using the Package Manager. If an error occurs while deploying a package, consult the error log file. The log file is located in the following folder:

[Experience Server install location]\crx-quickstart\logs

where [Experience Server install location] is the install location where the Experience Server is installed.

If you want to remove a package, you can do so by using the Package Manager. For example, assume that you are no longer using a specific package. In this situation, you can delete the package.

By default, when you deploy the package that is built by using the template application, the package's content is placed in the following repository path:

/apps/dataservices-example-app

Under the dataservices-example-app folder, you will find a bundles/install folder. The install folder contains a JAR file named dataservices-example-app-bundle-1.0-SNAPSHOT.jar. This JAR file contains the Java classes that you developed and placed in the template application's sourceCode folder. This JAR file is the bundle that belongs to the package that the template application created.

To deploy a package by using the Package Manager

  1. To view the Adobe Digital Enterprise Platform welcome page, enter the URL http://[host name]:[port] into a web browser. For example, http://localhost:4502.

  2. Enter a valid user name and password. You can use admin for both values.

  3. Click Packages.

  4. From the menu bar, click Upload Package.

  5. Navigate to the ZIP file that represents the package. Maven placed the ZIP file in the following folder: package/target.

  6. Click OK.

  7. From the new package entry menu, click Install.

  8. In the Install Package dialog, click Install.

To remove a package by using the Package Manager

  1. To view the Adobe Digital Enterprise Platform welcome page, enter the URL http://[host name]:[port] into a web browser. For example, http://localhost:4502.

  2. Enter a valid user name and password. You can use admin for both values.

  3. Click Packages.

  4. Select the name of the package to delete.

  5. From the menu, select More, Uninstall.

  6. In the Please confirm dialog, click Uninstall.

  7. From the menu, click More, Delete.

  8. In the Please confirm dialog, click Delete.

Using the Apache Felix Web Console Bundles view

You can use the Apache Felix Web Console Bundles view to confirm that your package was successfully deployed. If your package was successfully deployed, then it is displayed in the bundle view. You can view details about the package such as the packages it exports.

Note: It is recommended that you check the Apache Felix Web Console Bundles view to confirm that you package was successfully deployed. Click on the package to see details. Make sure that the Exported Packages value matches the package name that you specified in the POM file located in the sourceCode folder.

To confirm your package was deployed using the Apache Felix Web Console Bundles view

  1. To view the Adobe Digital Enterprise Platform welcome page, enter the URL http://[host name]:[port] into a web browser. For example, http://localhost:4502.

  2. Enter a valid user name and password. You can use admin for both values.

  3. Click OSGi console.

  4. Enter a valid user name and password. You can use admin for both values.

  5. Click the Bundles tab.

  6. Search for your bundle. You can order the bundle by version by clicking on the Version tab.

  7. Click on the arrow beside the package name to view its details.

Defining the server destination for the echo service

You define the server-side destination in Data Services XML configuration files. Data Services configuration files are located in the Experience Server repository. You can create and modify XML configuration files by using CRXDE Lite, which is available with the Experience Server.

Note: Instead of configuring a Data Services XML configuration file by using CRXDE Lite, you can place the XML configuration within a package. For information, see Create a Data Services application for the Experience Server that retrieves data from the sample database.

To successfully use the EchoService server-side class that you deployed within the Experience Services package, create a destination in the "remoting" destination configuration directory. Define a remoting destination that a client application references. A destination is the endpoint that you use to exchange data to provide data distribution and synchronization functionality in your client application.

Name your Remoting Service configuration XML file by using the following naming convention:

[Package name].xml
Note: You can name the Data Services XML configuration to meet your needs; however, it must end with .xml.

The name of the Remoting Service configuration file for EchoService is com.adobe.myexample.xml. Create this file in the following location:

/etc/aep/config/dataservices/destinations/remoting

The following example shows a destination named echo that is located in the com.adobe.myexample.xml file. The client application references the echo destination.

<?xml version="1.0" encoding="UTF-8"?> 
<destinations> 
<destination channels="my-amf" id="echo"> 
    <properties> 
        <source>com.adobe.myexample.EchoService</source> 
    </properties> 
</destination> 
</destinations>

Notice that the source element references com.adobe.myexample.EchoService. Also notice that the channel is my-amf. This channel is defined in the services-config.xml file.

If you do not define any channels in the destination, the default channels listed in the remoting-config.xml file is used. This file is located at /etc/aep/config/dataservices/remoting-config.xml.

For information about channels, see Channels and endpoints.

To define the server-side destination using CRXDE Lite

  1. To view the Adobe Digital Enterprise Platform welcome page, enter the URL http://[host name]:[port] into a web browser. For example, http://localhost:4502.

  2. Log in using admin as the user name and password.

  3. Click CRXDE Lite.

  4. From the left-side folder structure view, open /etc/aep/config/dataservices/destinations/remoting.

  5. Right click the remoting folder and select Create, Create File.

  6. Specify com.adobe.myexample.xml in the Name field.

  7. Click OK.

  8. Double click the com.adobe.myexample.xml file.

  9. Enter the XML shown in this section that represents the echo destination.

  10. From the top menu, click the Save All button.

Creating a Flash Builder client project for the Echo service

Create a Flash Builder project that is used to create the client application. This client application uses a RemoteObject instance to invoke the sayHello operation exposed by the echo destination. The following MXML code shows a RemoteObject instance that references the echo destination.

<fx:Declarations> 
        <!-- Connect to the echo ervice destination--> 
        <mx:RemoteObject id="echoOb" 
                         destination="echo" 
                         result="handleResult(event);" 
                         fault="handleFault(event);"/> 
</fx:Declarations>

The destination property links a client-side component to a destination that exists on the server.

The Flash Builder application is created by using a Flex Project for ADEP Experience Services. To create this type of project, install the Modeler plug-in. For information about installing the Modeler plug-in, see Installing ADEP Experience Services.

Note: Without the Modeler plug-in, you cannot create a Flex Project for ADEP Experience Services.

When you create a Flex Project for ADEP Experience Services, the required client SWC files are added to the project’s class path. Also, you do not have to define a channel instance that references the server. You specify the server’s IP address (or host name) when you set up a Flex Project for ADEP Experience Services.

The following MXML represents the client application that calls the sayHello operation supported by the echo destination.

<?xml version="1.0" encoding="utf-8"?> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
               xmlns:s="library://ns.adobe.com/flex/spark" 
               xmlns:mx="library://ns.adobe.com/flex/mx" minWidth="955" minHeight="600"> 
    <fx:Declarations> 
        <!-- Place non-visual elements (e.g., services, value objects) here --> 
         
        <!-- Connect to the echo ervice destination.--> 
        <mx:RemoteObject id="echoOb" 
                         destination="echo" 
                         result="handleResult(event);" 
                         fault="handleFault(event);"/> 
    </fx:Declarations> 
     
    <fx:Script> 
        <![CDATA[ 
            import mx.controls.Alert; 
            import mx.rpc.events.FaultEvent; 
            import mx.rpc.events.ResultEvent; 
             
            [Bindable] 
            public var echoResultString: String = ""; 
 
             
            public function handleResult(event:ResultEvent):void { 
                // Handle result by populating the TextArea control. 
                echoResultString = event.result as String 
                outputResult.text=echoResultString; 
                 
            } 
             
            public function handleFault(event:FaultEvent):void { 
                // Handle fault. 
                Alert.show(event.fault.faultString, "Fault"); 
            } 
        ]]> 
    </fx:Script> 
     
     
    <!-- Provide input data for calling the service. --> 
    <!-- Call the web service, use the text in a TextInput control as input data.--> 
     
    <!-- Display results data in the user interface. --> 
    <s:Button id="btnHello" x="296" y="28" label="Button" click="echoOb.sayHello(inputText.text)"/> 
    <s:TextInput id ="inputText" x="108" y="28"/> 
    <s:Label id="outputResult" x="109" y="78" text="Label"/> 
     
</s:Application>

To view server destinations

After you create a server destination, you can view it by using the Data Model perspective in a Flex Project for ADEP Experience Services project.

  1. Change the pespective to Data Model by clicking Window, Open Perspective, Data Model.

  2. View a destination by clicking Window, Show View, Destinations.

  3. Look for remoting destinations by searching in the Remoting Destinations folder.

To create a Flex Project for ADEP Experience Services application

  1. Start Flash Builder.

  2. Click File, New, Other.

  3. Select Flex Project for ADEP Experience Services and click Next.

  4. In the Project Name box, specify a name for your project.

  5. Under Application Type, select Web.

  6. Keep the Flex SDK version 4.5 and click Next.

  7. From the RDS server, select Experience Server (localhost).

  8. Click the Configure button.

  9. Select Experience Server.

  10. In the Host Name box, specify the hostname or IP address of the Experience Server.

  11. In the Port Number box, specify the Port Number.

  12. In the User Name, specify a user name. Specify a the corresponding password in the Password box.

  13. Determine if the project can communicate with the server by clicking the Test Connection button. If communication is successful, then a message that states that the test connection is successful is displayed.

  14. Click OK.

  15. Click Finish.

  16. Add the code displayed earlier to the MXML file.

  17. Click Project, Build All.

  18. Run the client application from your Flash Builder development environment by clicking the Run button.