That Java Thing, Part 8: Source Bundles

Tue Nov 10 07:46:28 EST 2015

Tags: java xpages
  1. Nov 02 2015 - That Java Thing, Part 1: The Java Problem in the Community
  2. Nov 03 2015 - That Java Thing, Part 2: Intro to OSGi
  3. Nov 04 2015 - That Java Thing, Part 3: Eclipse Prep
  4. Nov 05 2015 - That Java Thing, Part 4: Creating the Plugin
  5. Nov 06 2015 - That Java Thing, Part 5: Expanding the Plugin
  6. Nov 08 2015 - That Java Thing, Part 6: Creating the Feature and Update Site
  7. Nov 09 2015 - That Java Thing, Part 7: Adding a Managed Bean to the Plugin
  8. Nov 10 2015 - That Java Thing, Part 8: Source Bundles
  9. Nov 11 2015 - That Java Thing, Part 9: Expanding the Plugin - Jars
  10. Nov 12 2015 - That Java Thing, Part 10: Expanding the Plugin - Serving Resources
  11. Nov 16 2015 - That Java Thing, Interlude: Effective Java
  12. Dec 01 2015 - That Java Thing, Part 11: Diagnostics
  13. Dec 03 2015 - That Java Thing, Part 12: Expanding the Plugin - JAX-RS
  14. Feb 19 2016 - That Java Thing, Part 13: Introduction to Maven
  15. Feb 21 2016 - That Java Thing, Part 14: Maven Environment Setup
  16. Feb 22 2016 - That Java Thing, Part 15: Converting the Projects
  17. Feb 23 2016 - That Java Thing, Part 16: Maven Fallout
  18. Feb 26 2017 - That Java Thing, Part 17: My Current XPages Plug-in Dev Environment

Before anything else today, Eric McCormick reminding that yesterday's post missed the final step: committing the changes. So, let's take care of that right now. On my side, since my Windows VM is also being accessed from the Mac side, it's worthwhile to add a .gitignore file to the root of the repo to keep out all the .DS_Store nonsense. GitHub's Java gitignore is a good start, though skipping the part about ignoring Jar files. In your text editor of choice, create a new file named ".gitignore" in the root directory of the Git repository, with this content:

._*
Thumbs.db
.DS_Store

*.class

# Mobile Tools for Java (J2ME)
.mtj.tmp/

# Package Files #
#*.jar
*.war
*.ear

# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
hs_err_pid*

Then commit the files:

Now, on to today's topic: adding a source bundle. This is a small topic, but will be very useful as you work down the line. As it stands right now, even though you have access to the source code of your plugin, Designer doesn't, and that means that you don't have nice parameter names, inline Javadoc, or viewable source when working with your classes in an actual XPages application. Since XSP libraries are almost always open-source or internal-use-only, including a source bundle is the fastest way to achieve all of these.

The way to do this is pretty non-obvious, but not complex once you know what to do. The work will be done with a new feature project, so go to File → New → Other and then "Feature Project" within "Plug-in Development". This should be set up very similarly to the original feature:

  • Set the project name to "com.example.xsp.source.feature"
  • Override the location with a folder inside the Git repository
  • Pick a variant on your original feature name, so "Example XSP Library Source Feature"

Unlike before, however, we don't want to select any plugins on the next pane - instead, just hit "Finish". This feature is going to use some Eclipse trickery to automatically generate a "source" version of the existing feature. Once the project is created, open its feature.xml file and go to the "feature.xml" tab. On there, add a bit of XML to manually specify the non-existent source plugin (I've left out the "description", "copyright", and "license" blocks, which are required even if just stubs):

<?xml version="1.0" encoding="UTF-8"?>
<feature
      id="com.example.xsp.source.feature"
      label="Example XSP Library Source Feature"
      version="1.0.0.qualifier">

   <!-- *snip* -->

	<includes
         id="com.example.xsp.plugin.source"
         version="0.0.0"/>
</feature>

Then, go to the "build.properties" tab and add a second line to tell Eclipse's builder to generate the source plugin:

bin.includes = feature.xml
generate.feature@com.example.xsp.plugin.source = com.example.xsp.feature

Next, open the site.xml file in the update site project and add the new feature to the "Managing the Site" section:

Now, save and "Build All". Then, go back to Designer and install the latest version from the update site, which should now have a second feature listed:

When you install that and relaunch Notes/Designer, you'll be able to access the source of your plugin. To see this in action, open your application in Designer and then go to the "Package Explorer" view (you may have to add it via Window → Show Eclipse Views → Package Explorer). Find your NSF's project and expand the "Plug-in Dependencies" category. Towards the bottom, you should see the example plugin Jar file - expand that and double-click on one of the classes:

If all went well, you should see the source to the original class, instead of Eclipse's incomprehensible bytecode dump. Additionally, now, when you access these classes from Java code inside your NSF, you'll get improved inline help, with correct parameter names and Javadoc (if you actually write the Javadoc).

The next step will be another small but useful topic: adding some third-party Jars to your plugin, either to use internally or to expose to your XPages applications.

Commenter Photo

Georg Kastenhofer - Tue Feb 02 09:05:21 EST 2016

Hi Jesse,

thanks a lot for your perfect workup of these topics Lächelnd

One Hint: In the feature.xml description above you have posted a wrong include:

<includes id="com.example.xsp.plugin.sourceversion="0.0.0"/>

<includes id="com.example.xsp.feature" version="0.0.0"/>

 

Best regards

George

Commenter Photo

Georg Kastenhofer - Tue Feb 02 09:25:32 EST 2016

Hi Jesse,

sorry I was wrong, forget the hint of my previous comment.

Thank you again

George

New Comment