Creating a Java annotation

So I created a new (method-level) annotation that basically just takes a string, and when the target method is invoked, via aspect I get that string. The annotation looks like this (name changed to protect the innocent):

public @interface Annotatable { String value(); }

After a few hours of banging my head, trying to figure out why everything compiled correctly, yet when testing I could never get the find the annotation on the target method. Turns out, this was soooo poorly documented by Sun/Java gods, you need to annotate your annotation, like this:

import java.lang.annotation.*;

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Inherited


The RetentionPolicy enum tells the compiler to keep the annotation around AFTER you compile, instead of throwing it away (like it does by default). The Target annotation tells the compiler which types of elements your annotation can apply to (classes, methods, params, all, etc.). The long and short of it is: don't forget to annotate your annotations.

NUMA and the JVM

Good blog entry from Jon Masamitsu about NUMA optimizations in Java 6 on Solaris. NUMA, essentially, and vastly simplified, is to access a region of memory that is physically closer to a processer on a multi-processor system. This way there's less latency when reading/writing to the general memory region. For Java, the optimizations are made primarily to the Eden (young generation) heap space, as well as assigning a thread to a particular CPU.

To enable the feature. it's a command-line param to the JVM at startup: -XX:+UseNUMA .

Java 6 threading article

An article on Java 6 threading optimizations recently appeared on infoq. It's a good article in two parts, but here I'm just going to capture some of the interesting notes about the different locking features now in the JVM (most of this entry is paraphrase - that is, notes to myself).

Escape analysis - determine the scope of all references in an app. If HotSpot can determine the refs are limited to local scope and none can esacpe, it can have the JIT apply runtime optimizations.

Lock elision - when refs to a lock are limited to local scope (for example creating an modifying a StringBuffer), no other thread will ever have access to object; hence it is never contended for. Then, you really don't need the lock anyway and can be elided/omitted.

Biased Locking - most locks are never accessed by more than one thread, and even when multiple threads do share data, access is rarely contended. Long story short, this makes subsequent lock acquisitions less expensive by holding onto lock until somebody else wants it. Java 6 does this by default now.

Lock Coarsening (or merging) - occurs when adjacent synchronized blocks may be merged into one (if same lock is used for all methods). For example. when calling a series StringBuffer append() operations. Locks are not coarsened inside of a loop because the lock will be held for (potentially) too long.

Thread suspending versus spinning - When a thread waits for a lock, it is usually suspended by the OS. This involved taking it off the stack, rescheduling, etc. However, most locks are held for very brief time periods (based on profiling), so if the second just waits a little bit without being suspended, it can probably acquire the lock it wants. To wait it just goes into a busy loop - known as spin locking. Was introduced in Java 1.4.2 with a default (fixed) spin of 10 iterations before suspending the thread.

Adaptive Spinning - Spin duration not fixed anymore, but policy based on previous spin attempts on same lock and state of lock owner. If spinning likely to succeed, will go for a longer iterations count (say, 100); else, will bail on spinning altogether and suspend.
Introduced in Java 6.

devWorks Benchmarking article

This is a great article from the IBM devWorks site about Java performance benchmarking. I'm just capturing some notes in this entry.

Measuring time:

1. System.currentTimeMillis() - gets the "wall clock" time, but the updates from the OS are hardware dependent and may only occur every ~10 ms. call to OS returns instantly
   
2. System.nanoTime() - returns a differential time, measured in microseconds, bu the call to the OS itself can take microseconds.
3. ThreadMXBean - JMX extension that offers to read a Thread's CPU usage (may be misleading due to I/O and it's uage may be expensive)

Code warmup:

• Class loading can be observed via ClassLoadingMXBean
• Most VMs run the code for while in interpreted mode to gether stats before performing JIT compilation. Sun's Hot Spot defaults: 1500 time for client VMs, 10,000 for server. Could use CompilationMXBean to measure JIT time, but impl is hosed. Alternative is to watch stdout with -XX:+PrintCompilation JVM option
  

Grails + email service

Alright, finally getting back into to grails coding after a long time away. For my test pet store application, I decided to take a day and create newsletter sender. Basically, it just takes an email address (submitted via a little form widget thingy), and stores it in a separate table the database. I'm not bothering with user accounts yet for the site, so I'm just keeping it in a stupidly simple table with just a database id and the address itself. There's also a controller function for removing an address from the list (handy I should think).

Now that I've got email addresses to send to, I need to actually send the newsletters. Before tackling that, though, I want to send out the newsletters on a periodic basis, so i need a scheduling/cron like component. I decided to use the Quartz plugin for Grails. We use it at my $DAYJOB, and it's been an excellent workhorse there. After installing the plugin (grails install-plugin quartz), and creating a job (app-home/grails-app/job/SendNewletterJob.groovy), I was 80% done. I just had to define my scheduling and implement the execute() method, which calls my message send service. Easy! Here's my source:

class SendNewsletterJob {
def timeout = 9000l //runs every nine seconds (only for testing!)
def emailService

def execute() {
emailService.sendNewsletter()
}
}

Now for actually pushing the newsletter to the users. I created an app-home/grails-app/services/EmailService.groovy. In Grails parlance, from what I understand, a "service" is not a web-service (REST or SOAP), per se, but more like the Eric Evans DomainDrivenDesign notion of a service. Currently (May 2008) there is no nice plugin for sending email, but there is a nice document on the Grails site that describes how to create a mechinism that wraps Spring mail. I just ripped off the example EmailService, dropped my smtp host values into my grails-app/conf/spring/resources.xml, and I'm business.

Altogether, this project took less than four hours, most of which was fishing around playing with config settings and such. I'm trying to think what the parallel time investment would have been for a straight-up Java implementation. Hmmmmm.........

Pat Helland speech

Wow - another reason why Pat is truly one of my heros: Speech from 2007 TechEd EMEA

Starting with Grails

In an effort to branch out an learn my "one language per year" like a good little developer, I've decided to start tooling around with Groovy and it's most famous offspring, Grails. I spent a week on a test app just to get my feet wet with the Grails conventions for GSPs/Controllers/Domain object and such, and I must admit that it's been soooooo easy to get things up and running. And not having to recompile and bounce the web-app every time I make a change is nice - even though when I change a domain class the web-app bounces itself (controllers are better in this regard).

For a nice-sized project with Grails, I'm going to implement a basic e-commerce site as I have a little bit of experience in that domain :). I'm planning on attacking it in a TDD manner, and applying lots of YAGNI (wow, I really need to master that skill!). I'm also going to integrate with Google Checkout for doing purchases - all test/beta/sandbox, nothing for real. I've done integrations with credit card processors, loyalty point programs, and PayPal, so I figured I'd checkout Google's API and see what I find.

I'm also curious to see how grails can deal with HTTP header things like ETags and If-Modified and such. I'm not totally sure if that's the domain of the web-app or web server, but I'm itching to find out - as I'm on a limited bandwidth host, and I need to conserve by bandwidth bytes!

More reports as I progress.

Apache HTTP Client and proxy settings

I don't how many times I've had to do it (and how many times I've screwed it up), but I can never remember just how to set up proxies for Apache HTTP Client. So, to keep a record of my googling and experimenting, here's the entries that really helped:

• Java, Commons HTTP Client and HTTP proxies (Aaron Johnson). Check this the first example if you just need to set proxy name/host.
  

• jGuru - just the last thread comment (Vivek Singh - Aug 16, 2007). Check this out if you need to set authentication parameters, as well.
  

Essentially here's what I ended up with (if you just need proxy name and port):

HttpClient client = new HttpClient();
client.getHostConfiguration().setProxy(proxyHost, port);

Solaris Live Upgrade notes

Here's some handy tips for using Open Solaris Live Upgrade. Really, this is just my set of notes, most of which I've pilfered from this article. I'm not a Solaris expert my any stretch of the imagination, but this may be helpful to someone out there (even me....)

First, download the DVD ISO (or the separate CD images and cat them together). Then mount the ISO:
lofiadm -a /dev/lofi/1
mount -F hsfs -o ro /dev/lofi/1 /mnt

Install the new install packages (this is a separate step from the rest of the upgrade):
/mnt/Solaris_11/Tools/Installers/liveupgrade20 -noconsole -nodisplay
(runs in less than a minute)

If you have more than one existing slice (and you need to chuck it for space reasons):
ludelete -n
(runs in about 40 seconds)

Create a new slice by copying your original:
lucreate -c -n -m /::ufs
(this takes about two hours on my crappy ThinkPad)

Now, upgrade the new slice:
luupgrade -u -n -s /mnt
(this takes about two and a half hours on my crappy ThinkPad)

Finally, make it the actrive slice for the OS:
luactive
(runs in less than a minute)

If you are using a windowing environment, log out and and log into a command line terminal. Then:
init 6
and (if you're on a crappy ThinkPad), reboot.

Right-sizing the architecture

I work at a medium-sized technology company as an e-commerce architect. The company started out in the dot-com days supporting a single web site (primarily content driven). When I joined about two and a half years ago, the company decided to expand out into new sites hosting different content for different partners. As technologists, we decided break apart what was a monolithic application into separate services that could be reused amongst the sundry sites we would now be hosting. With SOA being a more accepted idiom at the time, we decided to build out a "platform" to handle our needs.

As for my role specifically in e-commerce, we have two aspects of the business: digital subscriptions and merchandise. The digital subscription e-commerce is handled in-house via home-brewed systems. The merchandise e-commerce engine and site was hosted and managed by third company. Early on in my requirements gathering for the e-commerce part of the new platform, there was talk of ditching off the external company and handling the merchandise ourselves. As the talk "seemed" rather serious, and the thought of running an e-commerce engine that handled both both merch and digital subscriptions sounded really fun, I decided to incorporate many of the merchandising aspects into my design up front. This problem number one.

As for the platform itself, it is a collection of synchronous web services and asynchronous message publishers/listeners. The web services are most SOAP-style, but there are a few REST services, as well. (I don't want to discuss the advantages of one web service technology over the other here, just the costs/implications involved with choosing one of them.) On the web services, we have a fully defined WSDL/XSD contract. For the messaging components, it's more-or-less a collection of name/value pairs (expressed as XML) going across the JMS, although some of the value elements are full XML documents conforming to a defined XSD. We found that specifying specifying the service interface and data entities via WSDL and XSD was helpful for defining the XML documents that would be exchanged between client and service, but that it's application was limited outside of that scope. This is problem number two, and the reason why it is a problem is largely dependent on problems number one.

The assumptions (and aspirations!) I started with unfortunately did not bear as much fruit as hoped. Let's start with problem number one. In my desire to design and build out a bad-ass e-commerce system, I jumped in full force. Given the requirements I had, I created what I call the "Big Vision Up Front". It's sort of a mix of Big Design Up Front (a/k/a/ the waterfall model) and the agilists' notion of YAGNI. Basically, I aggregated all the requirements and derived a vision of the future platform. This did not include hardcore UML diagrams or extensive documentation, but lots of collected thoughts about the various models and interactions amongst them. Then, as a given set of features that we knew were needed for the next project, we would build them out.

OK, this all seems cool so far, build components we need when we need them based on the original vision. Unfortunately, in the initial build out (call it phase 1), I built in more functionality, more of that big vision, than was necessary at the time. In other words, we overbuilt expecting that the unused components would be "needed soon". For some components that has turned out to be true (it may have taken a year or two, but they are finally being used). For others, it feels like random appendages hanging off in semi-sensibile directions. Of course much of this was due to my enthusiasm to create something big and great, but what I failed to recognize and understand was the nature of the business side of our, and really any, company. The business folks are, on the whole, nice people and are trying to do their jobs well. Unfortuantely, I didn't apply enough discretion to understand the business vision and goals in both the short and long terms and how I could apply my technical skills to best serve that. Hence, we overbuilt some things. Nothing awful or completely atrocious, but some design and code are growing a funky odor...

So, the lesson for problem one is to understand your business. Figure out what is really being asked for, both in the short and long term, and learn how to marry the two. Of course, this kind of knowledge only comes with experience, so I think I've begun down that path of enlightenment.

As for problem two, the purely technical matter: as part of taking over the merchandising site, we would have needed to integrate in with about 75 external partners (manufacturers, shippers, and such) and several other entities for user management, e-commerce, and miscellaneous services. With this in mind, we created full-blown WSDLs and XSDs (by hand - it's not that hard) as our service interfaces. Well, we built it, but nobody came. In fact, our only service consumers are internal. Now, having services even just for our internal clients (web-apps we host and so on) has turned out to be a great boon to seperation of concerns and being able to upgrade some of our sites without a big-bang release, there has been a development cost. We need to create the WSDL (basically define a few operations - we follow the SOAP Messaging style, not SOAP XML-RPC disaster), define the data structure in XSD, then create XML to object mapping files (we use JiBX) so everything gets populated into our domain models objects. This style isn't so bad once you've learned WSDL, XSD, JiBX, proper domain modeling, ...., but, there is a cost whenever we want to add a new operation to a service or create a new service. Everytime this happens, we keep looking at each other saying, "Something's just nor right here...". I feel that once again, we didn't understand our business fully and ended up satisfying their initial requirements but perhaps added in more infrastructure costs than what we really needed to incur.

So, the lesson for problem number two is to understand your business and know how to apply how the most cost-effective technology you can. By cost-effective, I don't necessarily mean cheapest in terms of licensing and deployment costs (although these factors cannot be totally discounted), I'm really talking about knowing your development team - the poor engineers who will have to implement and live with the architectural decisions. Ruby on Rails might (might?) be the best solution for a project in isolation, but if all your developers are Java cats with no Ruby (let alone Rails) experience, the cost of the project just went up. Similarly, the WS-* stack contains many inherent costs just to get something up and running.

To sum up, architects needs to keep eye on the business folks and the engineering resources who will be responsible for the building and ownership of the software we help them manifest. Otherwise it's a gonna be a long time in refactoring land....

JDeveloper 11g Jumps the Shark

I stopped using Eclipse about a year and a half ago because the performance (on a reasonably performant Mac) was just too abysmal. I then spent a month trying other IDEs (the free ones, at least - I'm cheap), and eventually settled on JDeveloper. It's not the best, but it had enough of what I needed - which is basically just Java editing and code complete. I really don't need all the crap they shove into all IDEs these days. Most importantly, it didn't take 30 seconds every time I wanted to switch edit buffers.

At that time JDeveloper was at version 10.3.something. About six or so months ago they started releasing the 11g technology previews of the IDE. I did notice a performance hit when running, as Oracle has started adding more and more features. But now (as of December), the third release of JDeveloper's tech preview was released, and I dropped my jaw when I saw the download size: nearly 700 MB. Honestly, the 10.x release was about one-fourth (maybe one-third) of that. After seeing that behemoth download, I realized my days with JDeveloper are almost over. With that much new code/bloat, there's no way it's going to be any more performant - my initial criteria. Yes, there may may be many new, nifty features - that all support Oracle's business, I understand this. And yes, it is a free IDE, so I get what I pay for. But even for hardcore Oracle users/shops, this upgrade just looks painful.

After this experience, I am considering going back to Eclipse, but there isn't any Solaris x86 build (except the 3.2 version on blastwave.org). Not that running on Solaris is a must, but it's what I've running on lately. Oh well, time to slum and try NetBeans, once again :).

Simplifying service interfaces - avoid database ids

Let's assume you have a data-centric (i.e. CRUD) service for retrieving product information. For the sake of simplicity, let's assume an XSD that looks like this:

<complexType name="product">
<sequence>
<element name="sku" type="string"/>
<element name="name" type="string"/>
<element name="description" type="string" minOccurs="0"/>
<element name="product-type" type="product-type"/>
</sequence>
</complexType>

<simpleType name="product-type">
<restriction base="string">
<enumeration value="apparel"/>
<enumeration value="subscriptions"/>
<enumeration value="digital_video"/>
</restriction>
</simpleType>

I'm defining a simple product that includes a product-type enum value, so a sample document would look like:

<product>
<sku>SHG876SHFW</sku>
<name>Navy Blue T-Shirt</name>
<description>A nice, blue shirt for your enjoyment!</description>
<product-type>apparel</product-type>
</product>

We explicitly want to keep the service interface simple and free of how things are represented within the service - meaning, not exposing database ids where they have no apparent meaning to a client of the system. Exposing the id of an entity like product seems reasonable, but is unconvincing for items such as lookup values, which in my designs have a unique integer id as well as a unique, human-readable name. The names should be immediately understandable to clients rather than needing a secondary lookup on their own end. For example, using "apparel" is much easier to understand than "4".

These lookup values I tend to treat as enum values in XML/XSD, and in the database they get their own row within a lookup table.

By asking to clients to pass in both an id and a unique name is bound for disaster - this typically happens with auto-generated code/service interfaces. So, for the simplest and easiest way to integrate, and to hide more of the internal nuts and bolts, I just use enum values in the interface.