Oracle Endeca Best Practices - Building Extensions
Building Easy to Maintain Java Extensions
As part of one of our engagements, we've been tasked with upgrading and enhancing a certain award-winning Oracle Endeca Information Discovery (OEID) application. One of the items on our plate last week was to uplift and upgrade an OEID Studio extension that enables record-level security. This integrated security manager had not been touched since it was delivered roughly 2 years ago.
As a first step, we asked for the original (old Endeca Latitude 1.x) source code so that we could begin the upgrade process. After scouring development, staging and production environments, we found the source code without too much issue. However, we also turned up 3 separate versions of the compiled JAR file with different sizes and timestamps. Talking to users of the application, everything has been functioning correctly but we had no way of figuring out if the 3 environments were functionally equivalent or if there were subtle differences that could be going undetected.
Now, this is not a unique problem and is probably all too common in the software world at large. Without getting into a lengthy dissertation regarding source control and continuous build and (Heaven, forbid!) Maven, we wanted to share some things that we do at Ranzal to make our lives and, more importantly, the lives of our customers easier.
Always Use Source Control
When in doubt, put it in source control. Whether it's an ETL workflow, a set of configuration files generated nightly, database scripts or even documentation, a little source control goes a long way. Personally, when we're talking source code, I like to put the source and the compiled code (.NET Assembly, JAR file, WAR file, etc.) into repositories side-by-side so that they're versioned together.
If you can automate the whole process, even better. Having your technical documentation in your source control repository is great as well so you never have to "hunt and fish" for the "gold standard" document.
Own the Component SDK
Partners and customers, in our experience, sometimes hesitate to "dive in" to SDKs and Extension points. If a code sample was provided or a project build file was generated, it is often treated as an immutable end product, rather than a starting point. We constantly answer questions from partners working on their first OEID project that can be traced back to blindly taking "Getting Started" or "Quickstart" files and treating them as "gospel" or including them where they're not necessary.
To bring this back to the world of Oracle Endeca extensions, in addition to recommending source control, we always package our Java source code as part of the delivered OEID asset. This gives customers more certainty when trying to match source code with deliverable as well as a "quick and easy" reference when troubleshooting issues as the code is right in front of you. Plus, once you understand the extension framework, you can do this easily with an insanely small tweak to the Ant Build XML files that are included with the SDK framework.
Locate the build-common-plugin.xml file in the components folder of your SDK installation. Using your favorite text editor, find the "war" target in the XML document and, within there, find the zip command.
Once there, the exclusion of source files from the final WAR file is actually pretty obvious:
If the "excludes" attribute is removed, the source code will now be packaged with the deployed WAR/JAR file.
Hopefully, people find this to be a helpful tip. It's saved us and our customers tons of time and frustration and is a terrific security blanket for anyone tasked with maintaining these applications.
It's just a small example of the value of "diving deep" into things like code-generation frameworks and quickstarts. Having the ability and the curiosity to understand these types of assets completely rather than treating them as something to be copy/pasted or avoided is one of the traits that we try to encourage in our employees, partners and customers.
We'll be sharing more of best practices going forward, if there's anything in particular you'd like to see, drop us a line.