That Java Thing, Part 8: Source Bundles
Tue Nov 10 07:46:28 EST 2015
- Nov 02 2015 - That Java Thing, Part 1: The Java Problem in the Community
- Nov 03 2015 - That Java Thing, Part 2: Intro to OSGi
- Nov 04 2015 - That Java Thing, Part 3: Eclipse Prep
- Nov 05 2015 - That Java Thing, Part 4: Creating the Plugin
- Nov 06 2015 - That Java Thing, Part 5: Expanding the Plugin
- Nov 08 2015 - That Java Thing, Part 6: Creating the Feature and Update Site
- Nov 09 2015 - That Java Thing, Part 7: Adding a Managed Bean to the Plugin
- Nov 10 2015 - That Java Thing, Part 8: Source Bundles
- Nov 11 2015 - That Java Thing, Part 9: Expanding the Plugin - Jars
- Nov 12 2015 - That Java Thing, Part 10: Expanding the Plugin - Serving Resources
- Nov 16 2015 - That Java Thing, Interlude: Effective Java
- Dec 01 2015 - That Java Thing, Part 11: Diagnostics
- Dec 03 2015 - That Java Thing, Part 12: Expanding the Plugin - JAX-RS
- Feb 19 2016 - That Java Thing, Part 13: Introduction to Maven
- Feb 21 2016 - That Java Thing, Part 14: Maven Environment Setup
- Feb 22 2016 - That Java Thing, Part 15: Converting the Projects
- Feb 23 2016 - That Java Thing, Part 16: Maven Fallout
- 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.
Georg Kastenhofer - Tue Feb 02 09:05:21 EST 2016
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 - 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