Make implementing Container's easier

[Matti Tahvonen]

There are several inconveniences in Container interfaces documentation (and perhaps a design also). This is a meta ticket and must be split for smaller peaces.

There are lots of methods, but not all of them are "required". Of course method must exist, but it doesn't have to do anything. Currently it is very hard for developer to know which of those must be implemented if they want to :

• use it in Table
• use it in Tree
• ...

Relocating "optional" methods from Container to sub interface would make things cleaner and simpler.

Also how to implement "optional" functions in interface is not that straightforward. JavaDoc's state that one should just return null, but methods are also defined to throw UnsupportedOperationException which encourages simply to throw an Exception. Example method below:

    /**
     * Creates a new Item into the Container, and assign it an automatic ID.
     * 
     * <p>
     * The new ID is returned, or <code>null</code> if the operation fails.
     * After a successful call you can use the {@link #getItem(Object ItemId)
     * <code>getItem</code>}method to fetch the Item.
     * </p>
     * 
     * <p>
     * This functionality is optional.
     * </p>
     * 
     * @return ID of the newly created Item, or <code>null</code> in case of a
     *         failure
     */
    public Object addItem() throws UnsupportedOperationException;

[Joonas Lehtinen]

Is this really a defect? Or should it be enhancement?