Article summary

Summary

Discusses how to create a basic OSGi bundle by using CRXDE.

Update: It is recommended that you no longer use CRXDE to create OSGi bundles for AEM. Instead use Maven. For information, see Creating your first AEM Service using an Adobe Maven Archetype project.

Digital Marketing Solution(s) Adobe Experience Manager (Adobe CQ)
Audience
Developer (beginner)
Required Skills
Java, XML
Tested On Adobe CQ 5.5

Introduction

You can create an OSGi bundle that can be used within the Adobe Digital Marketing Suite by using CDXDE. An OSGi bundle is essentially a Java module that contains application logic that meets your business requirements. An OSGi bundle lets you dynamically load, unload, configure, and control the Java module without restarting the server. CRXDE is the IDE that lets you develop applications for Adobe CQ (part of the Adobe Digital Marketing Suite).

An OSGi bundle can use third-party JAR files. That is, classes located within a third-party JAR file can be used within an OSGi bundle. To demonstrate how to create an OSGi bindle that uses a third-party JAR file, this development article uses a third-party JAR file and EchoService.jar. This JAR file contains the following basic Java class named EchoService2.

package com.adobe.myexample;

public class EchoService2 {
    
    public String sayHello(String val){
        
        return "Echo Service says: " +val ;
    }
}

Note:

Before following along with this development article, install Adobe CQ 5.5 and have it running. Also, ensure that you have CRXDE, which is the development environment. Finally create a JAR file named EchoService.jar and ensure that it contains the EchoService2 class shown above.

The objective of this article is to demonstrate how to create an Adobe CQ application that uses an OSGi bundle. The OSGi bundle uses the EchoService.jar file and makes use of the EchoService2 class. To create an Adobe CQ project that uses an OSGi bundle, perform these tasks:

  1. Create an Adobe CQ 5.5 application folder structure. 
  2. Create a template on which the page component is based. 
  3. Create a render component that uses the template.
  4. Create the OSGi bundle that uses the EchoService JAR file. 
  5. Modify the JSP to call a Java method defined in the OSGi bundle. 
  6. Create a new site that contains a page that displays content from the OSGi bundle.

Note:

There are different ways in which to create an OSGi bundle. For example, you can use Maven. For information, see Exploring the different ways to create an OSGi bundle for Adobe CQ.

Create an Adobe CQ folder structure

You can create an Adobe CQ application that contains templates, components, and pages. In this development article, you create an application that uses an OSGi bundle that makes use of the EchoService.jar file. Before you create application assets such as templates, components, pages, and an OSGi bundle, you create an application folder structure by using CRXDE Lite.

CQAppSetup

The following list describes each application folder:

  • application name: contains all of the resources that an application uses. The resources can be templates, pages, components, and so on. 
  • components: contains components that your application uses. 
  • page: contains page components. A page component is a script such as a JSP file. 
  • global: contains global components that your application uses
  • template: contains templates that you can base page components on. 
  •  src: contains source code that comprises an OSGi component (this development article creates an OSGi bundle in this folder.) 
  • install: contains a compiled OSGi bundles container

To create an application folder structure, perform these tasks:

  1. To view the Adobe CQ welcome page, enter the URL http://[host name]:[port] into a web browser. For example, http://localhost:4502.
  2. Select CRXDE Lite.
  3. Right-click the apps folder, select Create, Create Folder.
  4. Enter the folder name into the Create Folder dialog box. Enter myapp.
  5. Repeat steps 1-4 for each folder specified in the previous illustration. 
  6. Click the Save All button. 

Create a template

You can create a template by using CRXDE Lite. A CQ template enables you to define a consistent style for the pages in your application. A template comprises of nodes that specify the page structure. For more information about templates, see http://docs.adobe.com/docs/en/cq/current/developing/templates.html.

To create a template, perform these tasks:
1. To view the Adobe CQ welcome page, enter the URL http://[host name]:[port] into a web browser. For example, http://localhost:4502.
2. Select CRXDE Lite.
3. Right-click the template folder (within your application), select Create, Create Template.
4. Enter the following information into the Create Template dialog box:
Label: The name of the template to create. Enter apppage.
Title: The title that is assigned to the template
Description: The description that is assigned to the template
Resource Type: The component's path that is assigned to the template and copied to implementing pages. Enter myapp/components/page/apppage.
Ranking: The order (ascending) in which this template will appear in relation to other templates. Setting this value to 1 ensures that the template appears first in the list.
5. Add a path to Allowed Paths. Click on the plus sign and enter the following value: /content(/.*)?.
6. Click Next for Allowed Parents.
7. Select OK on Allowed Children.

Create a render component that uses the template

Components are re-usable modules that implement specific application logic to render the content of your web site. You can think of a component as a collection of scripts (for example, JSPs, Java servlets, and so on) that completely realize a specific function. In order to realize this functionality, it is your responsibility as a CQ developer to create scripts that perform specific functionality. For more information about components, see http://docs.adobe.com/docs/en/cq/current/developing/components.html.

Note:

By default, a component has at least one default script, identical to the component name.

To create a render component, perform these tasks:
1. To view the CQ welcome page, enter the URL http://[host name]:[port] into a web browser. For example, http://localhost:4502.
2. Select CRXDE Lite.
3. Right-click /apps/myapp/components/page, then select Create, Create Component.
4. Enter the following information into the Create Component dialog box:

  • Label: The name of the component to create. Enter apppage.
  • Title: The title that is assigned to the component.
  • Description: The description that is assigned to the template.

5. Select Next for Advanced Component Settings and Allowed Parents.
6. Select OK on Allowed Children.
7. Open the apppage.jps located at: /apps/myapp/components/page/apppage/apppage.jsp.
8. Enter the following JSP code:

<html>
<head>
<title>Hello World !!!</title>
</head>
<body>
<h2>This page is a placeholder</h2>
</body>
</html>

Create the OSGi bundle that uses the third party JAR file

You can use CRXDE to create the OSGi bundle that uses the EchoService.jar file. The OSGi bundle contains the following Java class named Echo.

package com.adobe.test;
import com.adobe.myexample.*;

public class Echo {
 
public String getMessage(String msg)
{
  EchoService2 echo = new EchoService2(); 
  String msg2 = echo.sayHello(msg);
   return msg2; 
   }

}

Notice that the Echo class contains a method named getMessage that contains application logic that creates an EchoService instance. Because the EchoService class is located within the EchoService.jar, this JAR file has to be located within the libs folder that belongs to the src folder.

The Echo class is located within a package named com.adobe.test. You create a folder structure to reflect the package name when you create the OSGi bundle. Otherwise an exception is thrown when a JPS calls the getMessage method.

When you create an OSGi bundle using CRXDE, a wizard assists you. The OSGi wizard creates the following folder structure under myapps:

  • src/main/java/com/adobe/test - contains the packages and the Java classes
  • src/main/resources - contains the resources used within the bundle
  • The Activator.java file – an optional listener class to be notified of bundle start and stop events

To create an OSGi bundle using CRXDE, perform these tasks:

  1. Start CRXDE and log in to your instance of Adobe CQ. 
  2. Select and right-click the myapp project’s OSGi bundle source directory (for example, /apps/myapp/src), then select Build, Create Bundle.
  3. Enter the Symbolic Bundle Name, Bundle Name, Bundle Description, and Package. Click Finish. For the package, enter com.adobe.test.
  4. Open the bundle's file com.adobebundleecho.bnd (or the name of the BND file). Verify that the text -SNAPSHOT has been added to the Bundle-Version. Also uncomment the Export-Package and Import-Package lines in the BND file. (If you do not uncomment these two lines, you will not be able to use the Java data types that are located within the JAR file.)
  5. Right click the libs folder and select Import File. Browse to the EchoService.jar file and import it into the libs folder. 
  6. Build the component by right-clicking the com.adobebundleecho.bnd file and selecting Build Bundle. This builds the OSGi bundle and uploads the Java types defined in the JAR file to the server. You can now create a Java class that uses the Java data types located in the JAR file.
  7. Create a Java class in the bundle source directory (src/main/java/com/adobe/test) by right-clicking the test folder and selecting New, Class.
  8. Enter Echo for the class name and place the Java code specified above into this class. Because you already built the OSGi bundle (in step 6), you can reference the EchoService2 class defined in the JAR file. 
  9. Select and right-click the Echo.java file and select Build, Compile.
  10. Rebuild the OSGi bundle by repeating step 6. Now the OSGi bundle contains the Echo class that you can call from a JSP that is part of a Page component.

Confirm that an OSGi bundle is successfully deployed

You can determine whether the OSGi bundle and its data types were successfully deployed by using the OSGi administrator. When you access this administrator view, you can click on the Bundles tab and view details about the bundle. The following illustration shows details about the OSGi bundle that is created in this article.

OSGiAdmin

You can view details, such as the Java packages that are part of the OSGi bundle. For example, notice that the com.adobe.myexample package is specified in the previous illustration. This package is defined in the EchoService.jar file that is part of the OSGi bundle.

To confirm that an OSGi bundle is successfully deployed, perform these tasks:

  1. To view the Adobe CQ welcome page, enter the URL http://[host name]:[port] into a web browser. For example, http://localhost:4502.
  2. Select OSGi Console and then specify the user name and password. 
  3. From the Adobe CQ5 Web Console Bundles view, select the Bundles tab. 
  4. Scroll to your bundle and right click on the arrow to view its details. You can see details, such as the Java packages that were imported.

Modify the apppage JSP to call the methods specified in the OSGi bundle

After you build the OSGi bundle and confirm that it has been deployed, you can call its methods from a JSP that is part of a page component. In this development article, the apppage JSP calls the getMessage method defined in the OSGi bundle’s Echo class. Modify this JSP so that it resembles the following JSP code.

<%@include file="/libs/foundation/global.jsp"%>
<%@ page import="com.adobe.test.Echo" %>
<h1><%= properties.get("title", currentPage.getTitle()) %></h1>
<%
Echo hw = new Echo();
%>
<h3><%= hw.getMessage("Hi There") %></h3>

Notice that a page import is specified and it imports the com.adobe.test.Echo. An Echo instance is created and its getMessage method is called.

To modify the apppage.jsp file, perform these tasks:

  1. To view the CQ welcome page, enter the URL: http://[host name]:[port] into a web browser. For example, http://localhost:4502.
  2. Select CRXDE Lite.
  3. Double-click /apps/myapp/components/page/apppage/apppage.jsp.
  4. Replace the JSP code with the new code shown in this section.
  5. Click Save All.

Create a page that displays data retrieved from the OSGi bundle

The final task that you perform in order to see a web page that displays data retrieved from an OSGi bundle is to create a page that is based on the apppage template (the template created earlier in this development article). The following illustration shows the data returned by the OSGi bundle being displayed in the web page. The string Hi There was passed as an argument to the getMessage method defined in the OSGi bundle.

OSGiwebpage

To create a web page that displays data retrieved from an OSGi bundle, perform these tasks:

  1. To view the CQ welcome page, enter the URL http://[host name]:[port] into a web browser. For example, http://localhost:4502.
  2. Select Websites.
  3. From the left hand pane, select Websites. 
  4. Select New, New Page.
  5. Specify the title of the page in the Title field. 
  6. Specify the name of the page in the Name field. 
  7. Select apppage from the template list that appears. This value represents the template that is created in this development article. If you do not see it, then repeat the steps in this development article. For example, if you made a typing mistake when entering in path information when creating the template, the template will not show up in the New Page dialog box. 
  8. Open the new page that you create by double-clicking it in the right pane. The new page opens in a web browser.

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy