I’ve renamed Spigot to DataValve, and moved it to the new site FlutterCode.com which will also host my other project called Knappsack which is a set of Maven archetypes for Java EE 6.

The new site will be home to most of my tutorials, articles and other writings, as well as possibly some screencasts and even podcasts. It will in essence be a pure java development site. This blog will go a bit quieter and contain less development stuff, although most opinion will get put out here instead of over there. I’ll also be copying some of my tutorials over there from this blog.

I’m aiming to create a fairly cohesive tutorial site, aided in part by the Maven Archetypes which will give me a firm base onto which I can build tutorials without having to start from scratch, but one archetype is a sandbox Java EE 6 app with project configuration, a demo model and some test data. The sandbox app will let developers create a new skeleton java EE 6 application they can play with. Building on that, there is a sandbox-demo application which as an archetype that creates a full working demo CRUD application using Java EE 6 so developers can see how all the different pieces of Java EE 6 go together. It includes features such as conversations, JPA CRUD, page parameters, CDI injection and events.

Again, I have to say it, but Open Source is Hard. In the past couple of months, I have been working on a whole new site, getting 2 projects ready to roll with documentation and site content to boot as well as working a job, and having some kind of life.

Now it’s out, I can start to focus a little more on getting some more Java EE 6 tutorials and articles out.

(Edit : I renamed this post so it doesn’t seem like Spigot is just for Seam, Spigot can be used with different frameworks or without any at all. However, I wrote this post since Spigot is so familiar to the Seam EntityQuery that it should be easy for Seam users to get the idea)

Seam developers should become familiar with Spigot concepts fairly quickly since they are very similar to those found in the Seam EntityQuery which was one of the main inspirations for the framework. If you imagine taking the entity query class and splitting it in two, one part to keep hold of state and the other to actually fetch the data. The stateful part is the Paginator that keeps track of what the current ordering of the data is, what is the current page and how big the pages are. The stateless part takes the Ejbql and the pagination information and returns a subset of the data. Now imaging that the data provider has the JPA pieces taken out and replaced with an abstract fetchResults method. This method is implemented in subclasses for specific data providers for text files, sql queries, jpa queries, native jpa queries, xml files, comma delimited or just an in memory dataset.

I also abstracted the concepts of parameterization and parameter resolution so you can have parameters on data providers that are no t query based and your parameters can be resolved using different mechanisms such as EL, reflection, a map, or using custom parameter resolution.
So really, for Seam developers, its like a Seam EntityQuery that doesn’t just use JPA, but uses any kind of data source you want but still returns just a list of objects.

Spigot works nicely with CDI and there is even a demo of it in the distribution that uses JSF and was generated using the Weld maven archetypes. Also, there is a Seam Jpa Dataset Adapter that you can use as a direct replacement for the EntityQuery which will adapt the entity query calls to the underlying data provider calls so you can have a seam-less transition if you want to switch over. This is still a little in-progress, but works. The one area that isn’t implemented is the sorting, which may not be possible, but I still need to add in the methods to the adapter even if they don’t do anything. The other issue is of course the configuration of the query from components.xml using the Seam Framework tags. However, you can define the query using regular component xml tags to define the Ejbql, restrictions and page sizes.

Two things to note if you start using Spigot in place of the entity query. All rows are returned by default, and you need to specify both a select statement and a count statement. I separated those two out so you can put join fetch phrases in the select statement without it breaking the count statement. There is an init method that you can use to set both of these statements for a class type.

It’s been a while since I’ve posted anything new as I’ve been busy with a new Open Source software project called Spigot. It’s a java library that sits between your application code and your data sources (Hibernate, JPA, JDBC or any arbitrary source of data) and helps with things like pagination and sorting using a common interface so you can switch out data providers and use alternatives.

For query language data providers, Spigot also facilitates excluding restrictions from WHERE clauses when parameters are resolved to null. Parameters are handled using parameter resolvers so there is more than one way to parameterize the query including EL expressions, reflection or a value map on the data provider.

Spigot also provides a few other add-ins like converting any dataset into an in-memory dataset that can itself be paginated and sorted and shared across an application (such as commonly used data in a web application). The IndexedDataProviderCache can give you random access into a dataset with caching and look ahead loading. This lets you hook a dataset with thousands of rows up to a Swing JTable with an instant response and a very small memory footprint since it doesn’t need to load all the objects at once as the provider will load the records as needed and cache the results. This is demonstrated in the Swing Demo in the download. There are also demos for Wicket and CDI with JSF.

You can ready about why I created Spigot in the documentation

Spigot is currently hosted on Project Kenai, where you can download the release, view documentation online or read about 10 ways Spigot helps developers.

public class Person {

  private Long id;
  private String firstName;
  private String lastName;
}

public class User extends Person {

  private String userName;
  private String password;

}

public class Customer extends Person {

  private int creditLimit;

}

public class Employee extends Person {

  private Date beginDate;
  private Date endDate;

}

The classic problems here are that a customer may not always be a person, and a person may be both a customer and a vendor and possibly even be an employee and user. It also ignites the age old debate of whether a user must be an employee or all employees are also users. Using inheritance severely restricts us by taking away our one chance to inherit from a single class and limits our future plans since we are claiming some hard rules such as “every user is a person”.

Also, how do we handle a person that leaves the company and comes back? Do we have two different instances of this person in the system? For that matter, most Person instances will be duplicated if a person is a customer and a user and employee. This also leads to problems with things like name changes where one version gets updated but the other doesn’t.

Role your own

One common solution to this problem is to let the Person entity have a collection of roles that they perform so they can be either a user,an employee, a customer or vendor at the same time. This does solve the problems of not having to worry about inheritance hierarchies and whether a user is an employee or vice versa and also lets a person play all those roles at once. However, it only works where you know that every user, customer, vendor or employee will be a person.
It’s also not very clear how we should reference these entities. If I have an order and need to reference a customer, do I reference the person or the persons customer role?

Compose Yourself

Alternatively you can use composition to model the relationship instead of inheritance. We can define a Person class which models just a person and we model Customers and Employees as separate classes that encapsulate the information specific to that role and has a reference to the person associated with it.The benefit here is that the different classes do not have to be subclassed from the Person class which lets us inherit from whatever we want.

public class User {

  private Long id;
  private String userName;
  private String password;
  private Person person;
}

and

public class Customer {

  private Long id;
  private Person person;
  private int creditLimit;
}

public class Employee {

  private Long id;
  private Person person;
  private Date beginDate;
  private Date endDate;
}

We don’t have to worry about whether Employee should inherit from a User or vice versa since they are entirely different entities but they reference the same person instance. We still have the ability to check for things like users that are employees by finding users and employees that have a matching person reference. Modeling for each of the entities is kept specific to what the entity represents. A customer contains customer information and an employee contains employee information with only a single reference to the person it is representing.

This solves our original problems, but also gives us far more in return. It is a far more flexible design because we can expand the definitions of the classes beyond the hard restriction that every customer must be a person. Let’s consider a situation where the developers have been asked to allow businesses to also be defined as customers in the system. With the Customer subclassing from Person design it would be a nightmare to change the code to accommodate this. On the other hand, if we designed Customer to use composition, we can easily resolve the problem.

public abstract class AbstractCustomer {

  private Long id;
  private int creditLimit;
  public abstract String getName();
}

We can create a person based customer by subclassing it and adding a reference to the person.

public class PersonCustomer extends AbstractCustomer {

  private Person person;

  public abstract String getName() {
    return person.getName();
  }
}

For a company based customer, we can again subclass it, this time adding a Company reference.

public class CompanyCustomer extends AbstractCustomer {

  private Company company;

  public abstract String getName() {
    return company.getName();
  }
}

Notice that in the abstract base class, we define the getName() method to return the name of the customer. This is made abstract and must be implemented in subclasses specific to the type of customer we are implementing. As a general rule, like any inheritance, common attributes that apply to all types of the entity should go in the base class because then you will be able to call those methods on references to the entity as the base class type instead of having to use a more specific subclass type. For example

  String msg = "Hi There "+customer.getName();

is much cleaner than

  String msg = "Hi There ";

  if (customer instanceof PersonCustomer) {
    msg = msg+((PersonCustomer)customer).getPerson.getPersonName();
  }

  if (customer instanceof CompanyCustomer) {
    msg = msg+((CompanyCustomer)customer).getCompany.getCompanyName();
  }

Another nice effect of this is modularity since you can add new customer types and the old queries will work the same way. For example, if you start with PersonCustomer you might have a query which lists the customers with a certain credit limit.

select c from Customer c where c.creditLimit > 500

If you suddenly add the CompanyCustomer class to the application, the query will still work and will now include company based customers in the list. Remember, the more attributes defined on the base class, the more attributes you will be able access or query on when obtaining instances as the base class. However, note that code driven attributes such as the getName() example above cannot be used for querying in JPA since the attribute does not resolve to a database field. To query by person name you would have to drop down to using the actual class name to query the name fields in the person reference.

Unique People, non-unique references

If an employee leaves the company and comes back, we can deal with this much easier because we can set the end date for the existing Employee instance when they leave and when they come back, we can create a new employee instance that references the same Person entity. We still only have one Person instance that is referenced by both Employee instances and thus there is no duplication. This kind of modeling is not only more accurate in that one person was an employee on two different occasions, but it also provides a form of auditing trail for that person. If you store the Employee reference, you can still use either the person or the employee id to search for data. If you wanted to see what orders this specific employee had filled in, you can search using either the employee id which would get the orders for this version of the employee only, or you could match based on the person id and see what orders that person had ever filled in as either employee instance. This also reflects the real world better since there is only ever one person, but they could have multiple periods as an employee.

Modeling with JPA

It is fairly easy to model the basic composition in JPA by adding a @ManyToOne annotation to the entity reference (in this case the person).

If you plan on creating subclasses that are backed by different entities (i.e. PersonCustomer and CompanyCustomer) then you have to choose between different inheritance strategies. If there only a few differences between subclasses, you can probably just use a single table. If there are bigger differences between the subclasses, you might want to use a joined table inheritance strategy while keeping the core attributes of the parent class in the main table.

For legacy databases, you could be faced with the problem that the referenced entity id, such as the company or person id in the customer subclass, is stored in the same field in the database record. You can use the same field name for the reference in the subclasses and JPA will work with it.

public class PersonCustomer extends AbstractCustomer {

  @ManyToOne
  @JoinColumn(name="REF_ID")
  private Person person;

}

public class CompanyCustomer extends AbstractCustomer {

  @ManyToOne
  @JoinColumn(name="REF_ID")
  private Company company;

}

Obviously, this method eliminates the opportunity to use foreign keys since a foreign key cannot reference two different tables. New designs should not use this method for this reason even though JPA allows it. If you let JPA drop and create the tables for you, with Hibernate at least, you will end up with a foreign key on the REF_ID field to either the person or company table that will be incorrect when you assign the other subclass type to it. Through luck, it may not raise an error the first time around (if you happen to have an instance of one entity that has the same Id as the other entity type) but it will at some point.

If you really need this design, then you can just build the tables yourself without the foreign key, but you should use a separate field even though it means that each record will have blank field in it. With a separate or join table inheritance strategy, you have no choice but to use separate fields for the references.

A technique with many uses

This technique has many applications, but I haven’t really seen it discussed that much. Obviously, most published application examples (i.e. Pet store or my own Issue Tracker) are trivial or incomplete so they don’t really require this level of attention to modeling detail. However you start to find all sorts of places this technique can be used for larger domain models either to provide functionality needed now or a flexible design to meet future requirements. Obviously, we don’t want to use this for everything in case we want to extend any object in our model, but refactoring models once you have gone live can be problematic as it not only involves code refactoring, but database refactoring as well. Adopting this technique early (i.e. pre production) in places it is likely to be needed can save a lot of headaches later on.

As another example, let’s say you wanted to define a Location which is basically an address and a few other attributes. These locations can be used for all sorts of things in various places in the application. We already have an Address class used throughout our code and we can embed it in our Location.

public class Location {

  @Embedded
  private Address address;

  private Date createdOn;
  private String description;

}

Half way through your project you find that since this location class is used everywhere, the needs have changed somewhat and in some places need to have a dynamic address that belongs to a person and needs to be updated when the persons address changes, and some places need a static fixed address that never changes (i.e. delivery address an order was sent to which never changes).

We can easily implement this by creating a Location class that is subclassed into the different implementations that source the address from different places.

public abstract class Location {

  public Address getAddress();
  private String description;
  private Date createdOn;

}

public class FixedLocation extends Location {
  @Embedded
  private Address address;

  public Address getAddress() {
    return address;
  }
}

public class PersonLocation extends Location {

  @ManyToOne
  private Person person;

  public Address getAddress() {
    return person.getPrimaryAddress();
  }

}

Not only have we provided a solution for our fixed and dynamic address problem, since FixedLocation will store the address internally while the others will dynamically obtain the latest address from the Person, but we have provided a structure that will allow us to turn any entity into an address provider for our Location class. In some ways, we are using it as more of an adapter pattern since the address sources no longer have a common type. We are using an adapter pattern to make the different implementation sources fit with our Location interface.

I have found a number of uses for such compositions/adapters in places where inheritance would have severely limited my options or provided some difficult challenges, and by implementing this concept I’ve been able to make my models far more flexible and be able to accommodate new needs quickly.

Glassfish v3 which implements the full JEE 6 stack has also been released, with JBoss’ Weld as the CDI implementation. Netbeans 6.8 has also been released with full JEE 6 project support including maven support for enterprise applications. Also of note is the hot deploy function of Glassfish which can deploy your app while maintaining session information.

Personally, I’m pleased. JEE 6 has really improved things for the java standards, and CDI has filled some gaps that previously required different additional pieces to completely fill. The ghosts of EJB 2.1 should now be permanently laid to rest, but should serve as a stark reminder. Having good frameworks to build standards based solutions is always good for the community.

I’ll try and get some tutorials on developing with CDI and JSF 2.0 with Netbeans and Glassfish out soon.

(note This post relates to both the milestone 2 and beta versions of Netbeans 6.8 which I have been tinkering with over the duration of this article being written.)

The download for Netbeans 6.8 comes with Glassfish v3 which implements JEE 6 including JSF 2.0 and JPA 2.0.

Glassfish now has really fast hot deployment so you can change a line of code, save it, and it re-deploys instantly which in my opinion, this is a huge productivity booster. This isn’t limited to Netbeans, the eclipse plugins also provide this feature, and it works with pretty much any framework. I tried it with Wicket and Spring MVC and it was fantastic to get a wicket error where I had forgotten to add a component, so I go back to the java page code, add the component, refresh my browser and it works. Glassfish now has support for JEE 6 so you can make a pojo a local EJB just by adding the @stateless annotation to it. You can also deploy EJBs in war files as well without needing the whole EAR setup. One problem I did see was that when you used the EAR project setup with an EJB and War project, the hot deploy didn’t appear to work as well. Changes to the war file didn’t appear to redeploy, maybe because it is the EAR file that is deployed and not the war. However, still fantastic stuff.

Netbeans 6.8 beta was released in the last week or so. Feature-wise it is a great product with better tooling for JSF, including JSF 2.0, facelets support, and auto-completion for JSF backing beans in the JSF page. It also includes support for JEE 6, EJB 3.1, JPA 2.0 and development with Glassfish v3. It also improves upon the existing Maven support by providing for mavenized Ear projects.

While the features are impressive, Netbeans still seems hindered by performance issues and some minor bugs (although it is a milestone/beta release). Personally, I found this release no more sluggish that other releases although some people in the forums have had worse experiences. Netbeans strength has always been that it offers one standard solution without the plugin nightmares that eclipse has. While Netbeans has plugins they are more like installable features, they have a higher granularity than Eclipse plugins which is more like DLL hell. That said, I use Eclipse at work and it is always hard to shift from one keyboard mapping to another, and Eclipse does seem faster without the intermittent pauses. However, right now, Netbeans is a superior product in terms of features, especially for a JSF developer. I’d keep an eye out for the 6.8 final release to see how it comes out, and give 6.8 milestone 2 a go just to enjoy the experience if you are interested in using a standards based stack because thats obviously where the Netbeans folks are focused.

One big issue I have with Netbeans is the oddness of some of the key mappings. I think in nearly every application I use I press Alt+F and then C to close the currently edited document. Whether is it in MS Office, Borland Delphi, Eclipse, Firefox, while in the file menu, the C key always closes the currently open document you are editing. In Netbeans, it closes the currently edited project which means suddenly my project disappears when I want to close an edited file. Another is the use of Ctrl+Space for invoking auto completion which in Netbeans sends focus to the project manager or something like that. Sure, I can change the keymappings, such as to the Eclipse profile, but then I’m using some arbitrary weird key mapping which isn’t Netbeans and it isn’t completely the same as Eclipse. It is probably this way for legacy reasons, but some of these key presses are de facto standards.

Lastly, we come to JSF 2.0 which was forged from JSF 1.2 and the litany of complaints about it. The JSR group looked at the solutions out in the wild that already work around those problems (many of which were written by people in that very group) and incorporates those fixes in a standard JSF API type of way. Primarily we have the dropping of JSP as the default view in exchange for the Facelets / JSF templating solution. This also lent itself very well to easier component creation including no-code components. There is now zero configuration required except for the servlet in web.xml and managed beans can now be defined using annotations. Navigation which also used to be in the faces-config.xml is also more convention of configuration. Another big request was the inclusion of AJAX awareness in the JSF lifecycle . It provides the bare minimum features that 3rd party developers can build upon using the standard API instead of their own AJAX solutions. There is better support for GET requests and page parameters as well as invoking actions on page requests which is a feature often used in Seam.
There is also some performance boosts with regards to re-working state saving and the resource access mechanisms have been improved a great deal.

Also noteworthy is the inclusion of Weld CR 1 which is the reference implementation of JSR 299 – Java Contexts and Dependency Injection from JBoss. Admittedly, I haven’t really gotten round to taking a look at it, but from what I have seen and read so far, it looks like it fills some gaps in the JEE 6 platform and is up to par with the new found simplicity and strength that JEE 6 is promoting right now.

Overall, this is a pretty exciting set of tools and framworks and well worth a look if you are interested in adopting a standards based stack.

We could make the instance managed before we save it or assign it to the property, but this is a session scoped instance, and it could be shared among multiple conversations. We may want to compare the instances at different times in the same conversation which will break if it has been altered by another conversation. Also, we don’t want to have to write code to handle each property assignment or saving each entity type.

The answer is to have a locally scoped instance of the user that is generated from the session scoped instance. We create a new conversationally scoped bean which will hold the factory for the scoped user instance. The factory method takes the session scoped User instance and merges it with the current entity
manager to get a locally usable instance.

@Name("scopedUserBean")
@Scope(ScopeType.CONVERSATION)
public class ScopedUserBean {

  @In
  private User user;  //injection point for session scoped user

  @In
  private EntityManager entityManager;  

  @Factory("scopedUser")
  public User getScopedUser() {
    return (User) entityManager.merge(user);
  }

}

Now, when we want to reference the user in locally scoped fashion, we can do so using the scopedUser variable. Note also that we can compare the instances either in the server side bean, or even in the JSF page.

@Name("caseEditor")
@Scope(ScopeType.CONVERSATION)
public class CaseEditorBean{

  @In
  private User scopedUser;  

  @In
  private EntityManager entityManager;

  @In
  private Case case;  

  //we can compare scoped user to
  public void closeCase() {
    if (case.createdBy == scopedUser) {
      //this is the users case, they can close it
    } else {
      //this is not your case, you can't close it!
    }
  }

  public String saveCase() {
    case.createdBy = scopedUser;
    entityManager.persist(case);
  }

We can compare the instance on the case with the instance from scopedUser because they are the same instance in the same conversation, and even perform comparisons in EL expressions.