That Java Thing, Part 8: Source Bundles
Nov 10, 2015, 7:46 AM
- That Java Thing, Part 1: The Java Problem in the Community
- That Java Thing, Part 2: Intro to OSGi
- That Java Thing, Part 3: Eclipse Prep
- That Java Thing, Part 4: Creating the Plugin
- That Java Thing, Part 5: Expanding the Plugin
- That Java Thing, Part 6: Creating the Feature and Update Site
- That Java Thing, Part 7: Adding a Managed Bean to the Plugin
- That Java Thing, Part 8: Source Bundles
- That Java Thing, Part 9: Expanding the Plugin - Jars
- That Java Thing, Part 10: Expanding the Plugin - Serving Resources
- That Java Thing, Interlude: Effective Java
- That Java Thing, Part 11: Diagnostics
- That Java Thing, Part 12: Expanding the Plugin - JAX-RS
- That Java Thing, Part 13: Introduction to Maven
- That Java Thing, Part 14: Maven Environment Setup
- That Java Thing, Part 15: Converting the Projects
- That Java Thing, Part 16: Maven Fallout
- 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.
Georg Kastenhofer - Feb 2, 2016, 9:05 AM
Hi Jesse,
thanks a lot for your perfect workup of these topics
One Hint: In the feature.xml description above you have posted a wrong include:
<
includes
id
=
"
com.example.xsp.plugin.source"version
=
"0.0.0"
/>
<
includes
id
=
"com.example.xsp.feature"
version
=
"0.0.0"
/>
Best regards
George
Georg Kastenhofer - Feb 2, 2016, 9:25 AM
Hi Jesse,
sorry I was wrong, forget the hint of my previous comment.
Thank you again
George