AR System APIs Quick Start Java - Dev Environment Setup

Version 1
    Share This:

    This is the first part of the BMC Remedy Java API Tutorial.  In this document we will cover off getting our development environment ready to work with the BMC Java API.

     

    In order to begin using the Remedy API, you should have the following on your computer:

     

    • Oracle Jave Developer Kit (JDK) 1.6+
    • BMC Remedy Java API libraries (arapiXX_buildXXX.jar) – libraries are named according to their version, for example an unpatched 8.1 api library would be named “arapi81_build001.jar”
    • BMC Remedy Java API Javadocs (ardocXX_buildXXX.jar) – libraries are named according to their version, for example an unpatched 8.1 api javadoc would be named “ardoc81_build001.jar”
    • Apache Log4J libraries (log4jX.X_XX.jar) – libraries are named according to their version
    • A Java IDE such as Eclipse or Intellij IDEA

     

    With all of the above we are ready to begin exploring the API.  In the next section, we will overview the setup required to have a working development environment based on the above requirements.

     

    Environment Setup


    Assume that you already have installed a compatible version of the Oracle JDK and that you have access to the BMC and Apache libraries noted above. Our first step will be the configuration of our IDE.  For the purposes of this document, all instructions are based upon Intellij IDEA (a free version can be found at http://www.jetbrains.com/idea/download/index.html).  After installing and configuring your IDE to point to your JDK installation, you can create a project which will include all the necessary libraries to interact with the BMC Remedy Java API.

    Below are the steps to setting up a shell project

     

    1. Launch Intellij IDEA
    2. Create a new Project
      1. Select Java Module
      2. Name your project appropriately
      3. Select the proper JDK for the project
      4. Click Next
    3. Click Finish

     

    You now have an empty Java project that is ready for adding Remedy API libraries to.  In order to add the libraries, they must be on your system.  If you have a BMC Remedy instance installed on your system, the libraries will be included in the following path (assuming the default path was used during installation)

     

    C:\Program Files\BMC Software\ARSystem\Arserver\api\lib\


    If you do not have a local installation and instead will be connecting to a remote system, you will need to source the required libraries on your own, see section above for which jar files are required.

     

    To add the local libraries to your project, you must perform the following actions:

     

    1. Click on File menu
    2. Click on Project Structure
    3. Click on Modules from the left hand navigation pane
    4. Click in Dependencies tab in the right most panel
    5. Click the green + icon on the right most panel
      1. Select “Jars or Directory”
      2. Navigate to where library files are located and select both arapiXX_buildXXX.jar and log4jX.X_XX.jar
      3. Click OK
    6. Click OK

     

    Alternatively, you can create a lib folder in the root of your project, copy the arapiXX_buildXXX.jar and log4jX.X_XX.jar files into it and then make it a library folder by right clicking on it in Intellij and then selecting "Add as Library" towards the bottom and then click OK to the prompt and the lib folder and all the Jars within will be added as libraries to your project.

     

    That is all that is required to minimally setup a project that will have the necessary libraries to interact with the Remedy API.  You are now free to create a new Java Package & Class file and it will be able to import the needed Remedy API Libraries. For the purposes of these examples, I will not provide a package however it is strongly recommended to create a package under the src folder and create your Classes within.  Examples within this document will use “Tutorial” as the Class name.

     

    Remedy API Javadocs


    In order to truly understand and be able to work with the Remedy API, access to the API documentation is critical and will be referenced throughout this document.  The location of the API documentation is the same as the jar files previously discussed and by default could be:

     

    C:\Program Files\BMC Software\ARSystem\Arserver\api\lib\

     

    If you do not have a local installation and instead will be connecting to a remote system, you will need to source the required file on your own, see section above for which jar file is required.

     

    The name of the API documentation jar file is ardocXX_buildXXX.jar.  Once you have your ardocXX_buildXXX.jar file, you simply need to extract the jar file the same way you would a zip file.  It will create a directory structure that begins with the same name of the file with a large tree of nested folders and files below it.  The important file to begin with is the index.html which can be opened in any browser and this will give you full access to the API documentation

     

    Here is a snip of what it may look like opened in a browser:

     

    BMCJavaAPIDocScreenshot.png

      

    The format is a standard template Java doc format with class listings on the left and content on the right.

     

    Integrating the Java docs into the IDE itself has many advantages as well to reduce the need of browsing the full Java docs via browser each time.  In order to integrate the Remedy API Javadocs into the Intellij IDEA IDE, we must attach it to our Remedy API Library:


    1. Click on File Menu
    2. Click on Project Structure
    3. Click on Modules from the left hand navigation pane
    4. Click in Dependencies tab in the right most panel
    5. Select the Remedy API library from the window and then click the Edit button (pencil icon)
      1. From the edit window, click on the green + icon and then select “Attach files or directory”
      2. Navigate to where Javadoc jar file is located and select ardocXX_buildXXX.jar, this will add it as a Javadoc related to the Remedy API library
      3. Click Ok
    6. Click OK

     

    Now, when you are typing in Class names, Methods, Constants, etc., you will have the documentation available if you hit Ctrl+q on your keyboard or if you configure the documentation to always show when selecting by performing the following:


    1. Click on File Menu
    2. Click on Settings
    3. Expand Editor from the navigation pane
    4. Select Code Completion
    5. Check the box next to the option for “Autopopup documentation in (ms)” and set the amount of time, the default 1000 is typically fine as sometimes as you are typing you don’t want the documentation to constantly be refreshing, only once you have stopped typing for 1 second for it to display the documentation on the object you currently are on.  If ever the documentation doesn’t show, you can always hit Ctrl +q

     

    You now should have a working Java IDE that is setup to work with the BMC Remedy Java API.

     

    Click here to navigate back to the main AR System APIs Quick Start Java page to continue the tutorial.