001    package edu.nrao.sss.sort;
002    
003    /**
004     * An object that has a {@link SortOrder sort order}.
005     * <p>
006     * <b>Version Info:</b>
007     * <table style="margin-left:2em">
008     *   <tr><td>$Revision: 593 $</td></tr>
009     *   <tr><td>$Date: 2007-05-07 15:54:14 -0600 (Mon, 07 May 2007) $</td></tr>
010     *   <tr><td>$Author: dharland $</td></tr>
011     * </table></p>
012     * 
013     * @author David M. Harland
014     * @since 2007-05-04
015     */
016    public interface Orderable
017    {
018      /**
019       * Sets the order to {@code newOrder}.
020       * <p>
021       * Implementing classes should handle a <i>null</i> parameter in some way
022       * other than merely saving it and waiting for a downstream
023       * {@code NullPointerException}.  Typical responses would be to replace
024       * <i>null</i> with some valid value, such as {@code SortOrder.NATURAL},
025       * or to throw an {@code IllegalArgumentException}.</p>
026       * 
027       * @param newOrder the new order for sorting.
028       */
029      public void setOrder(SortOrder newOrder);
030      
031      /**
032       * Returns the sort order.
033       * <p>
034       * Implementing classes should guarantee that the returned value will
035       * never be <i>null</i>.</p>
036       * 
037       * @return the sort order.
038       */
039      public SortOrder getOrder();
040    }