Skip to end of metadata
Go to start of metadata

This section covers creating a plugin skeleton and launching it in the Atlassian Reference Application (RefApp). RefApp is a lightweight web application built for the sole purpose of developing plugins that work in any Atlassian application. If your plugin works in RefApp, you can run it in any other Atlassian application. 

This section of the tutorial walks you through the following topics: 

Get introduced to RefApp

We use RefApp intentionally in this tutorial. RefApp is a tool uniquely suited to plugin development: No Atlassian application is identical, but the RefApp provides the shared framework between all Atlassian applications. This means that you can develop your plugin without accidentally relying on dependencies or features specific to one application, or encountering an application-specific bug later on. Developing a plugin with RefApp eliminates guesswork about the functionality of your project. You can rest assured that since all Atlassian applications share at least the framework present in RefApp, your plugin will work as expected.  

RefApp features common components like SAL (Secure access layer) or the REST API browser (we won't be using REST in this tutorial). 

While the RefApp might not be much to look at, it's the perfect place to start your plugin development:

 

Step 1. Create a skeleton

Here, you'll create the foundation for your plugin project in the form of a plugin skeleton. Maven builds the plugin skeleton as Java and XML files, and downloads dependencies necessary for your plugin project. 

  1. Create a directory called atlastutorial

    $ mkdir atlastutorial
  2. Change to your new atlastutorial directory. 

    $ cd atlastutorial
  3. Generate a skeleton for your add-on. 

    $ atlas-create-refapp-plugin
  4. Create the following when prompted.

    Press return or enter to accept default values shown in brackets. 

    groupIdcom.atlassian.plugins.tutorial.refapp
    artifactIdadminUI
    version1.0-SNAPSHOT
    packagecom.atlassian.plugins.tutorial.refapp
  5. Confirm your entries when prompted with Y or y.

    The code generation runs to completion. You'll see a message similar to the following: 

    [INFO]
    -------------------------------------------------------------------- 
    [INFO] BUILD SUCCESSFUL 
    [INFO] 
    -------------------------------------------------------------------- 
    [INFO] Total time: 36 seconds [INFO] Finished at: Mon Jun 17 11:22:49 PDT 2013 
    [INFO]
     --------------------------------------------------------------------
  6. Change to the newly created adminUI project root.

    $ cd adminUI/


  7. Remove the test directories.

    $ rm -rf src/test/java/
    $ rm -rf src/test/resources/

    These directories are automatically created from atlas-create-refapp-plugin, but testing isn't part of this tutorial. Removing them simplifies your work in future steps.

  8. Remove Java classes from the src/main/java directory: 

    $ rm ./src/main/java/com/atlassian/plugins/tutorial/refapp/*.java

    You'll create a single Java class encapsulating your plugin logic in later steps.

Step 2. Start up the RefApp

When you generated the skeleton for your plugin, you specified a RefApp plugin skeleton. Your plugin has access to the shared application services and developer tools for all Atlassian applications. Here you'll start up the RefApp and get better acquainted with your resources.

  1. Change directory to your project root. 

    $ cd adminUI
  2. Enter the following command to start up RefApp:

    $ atlas-run
  3. Locate the RefApp URL.
    After a few moments your terminal will display a message with the URL of the application. RefApp usually launches on port 5990. 

    [INFO] [talledLocalContainer] Tomcat 6.x started on port [5990] 
    [INFO] refapp started successfully in 46s at http://localhost:5990/refapp 
    [INFO] Type Ctrl-D to shutdown gracefully [INFO] Type Ctrl-C to exit
  4. Copy the URL and paste it into your browser. 

  5. The URL will resemble http://localhost:5990/refapp.

  6. Click Login from the upper right-hand corner.
  7. Log in with the username admin and the password admin.
  8. Click Login.

  9. Click A.D. Ministrator (Sysadmin).

    Under the GeneralApplication Links, and Developer Toolbox you'll see the core components shared by all Atlassian applications:


Optional: Import your project into Eclipse IDE

You've launched RefApp from your adminUI project root using just the command line. Now, let's import adminUI into Eclipse so you can make code changes more easily.

Start from a new tab in your terminal:

  1. Change directory to your project root. 

    $ cd adminUI
  2. Make your project available to Eclipse. 

    $ atlas-mvn eclipse:eclipse
  3. Start Eclipse.
    You can open a new tab in your terminal and run the following commands to open Eclipse. 

    $ cd ~/eclipse 
    $ ./eclipse
  4. Click File > Import.

  5. Under General, choose Existing Projects into Workspace.
     
  6. Click Next.

  7. Choose Select root directory.

  8. Click Browse.
  9. Choose your project's parent directory, atlastutorial
  10. Click Open.

  11. Confirm your adminUI project appears in the Projects window.
    If you don't see your project, ensure you run atlas-mvn eclipse:eclipse while in your adminUI directory.

  12. Click Finish.

Next Steps

Now that your plugin skeleton is built and imported into Eclipse, you'll construct a servlet.

  • No labels

5 Comments

  1. Anonymous

    the atlas-run command in step 2 stage 2 has hung at:

    [INFO] [talledLocalContainer] - META-INF/services/com.sun.org.apache.xalan.internal.xsltc.dom.XSLTCDTMManager

    is there any way around this? I am on windows 7 and using cmd with admin access.

    1. Hi there,

      We might need more information to accurately diagnose this issue, but it looks a lot like the issue described here: https://answers.atlassian.com/questions/194050/need-help-with-create-a-plugin-skeleton-tutorial-dependency-issues

      Is it possible that the app started successfully? Can you navigate to http://localhost:5990/refapp

      If not, let me know what other messages you're seeing when you run atlas-run from the adminUI project root.  

      Good luck!

  2. Anonymous

    same problem here, hangs at the last line below.ee

    ubuntu 12.04 LTS

    java version "1.6.0_27"

    OpenJDK Runtime Environment (IcedTea6 1.12.6) (6b27-1.12.6-1ubuntu0.12.04.2)

    OpenJDK 64-Bit Server VM (build 20.0-b12, mixed mode)

     

    [INFO] [talledLocalContainer] - META-INF/services/org.apache.xerces.xni.parser.XMLParserConfiguration
    [INFO] [talledLocalContainer] - META-INF/services/javax.xml.transform.TransformerFactory
    [INFO] [talledLocalContainer] - META-INF/services/com.sun.org.apache.xalan.internal.xsltc.dom.XSLTCDTMManager
    [INFO] [talledLocalContainer] Warning:  The encoding 'UTF-8' is not supported by the Java runtime.
    [INFO] [talledLocalContainer] - META-INF/services/org.apache.xerces.xni.parser.XMLParserConfiguration
    [INFO] [talledLocalContainer] - META-INF/services/javax.xml.transform.TransformerFactory
    [INFO] [talledLocalContainer] - META-INF/services/com.sun.org.apache.xalan.internal.xsltc.dom.XSLTCDTMManager
    [INFO] [talledLocalContainer] Warning:  The encoding 'UTF-8' is not supported by the Java runtime.
    1. I have same problem like about. Here is my computer info.

      Apache Maven 2.1.0 (r755702; 2009-03-19 02:10:27+0700)
      Java version: 1.7.0_17
      Java home: D:\Development\Java\1.7\jre
      Default locale: en_US, platform encoding: Cp1252
      OS name: "windows 7" version: "6.1" arch: "amd64" Family: "windows" 

       

      Anyone can help me?

      Thanks in advance. 

  3. Hi there,

    Unlike Confluence or JIRA, RefApp spits out many [INFO] messages after the success message and URL. The most common issue we see here is that it started successfully, but the success message is buried behind a long trail of [INFO] messages. Most often you should be able to navigate to  http://localhost:5990/refapp – have you given this a try?