001    /**
002     * Copyright 2009-2010 by The Broad Institute.
003     *
004     */
005    package org.broadinstitute.genee.matrix;
006    
007    /**
008     * Stores annotations for the rows or columns of a dataset.
009     */
010    public interface MetadataModel {
011    
012        /**
013         * Appends the specified column name to the end of this meta data (optional
014         * operation).
015         * 
016         * @param columnName
017         *            The column name to be inserted into this meta data instance.
018         * @param columnClass
019         *            The class of the column to be inserted.
020         * @return the added vector.
021         * @throws UnsupportedOperationException
022         *             if the <tt>addColumn</tt> method is not supported by this
023         *             meta data instance.
024         */
025        public Vector add(String columnName, Class<?> columnClass);
026    
027        /**
028         * Returns the vector at the specified metadata index.
029         * 
030         * @param metadataIndex
031         *            the metadata index
032         * @return the vector
033         */
034        public Vector get(int metadataIndex);
035    
036        /**
037         * Returns the vector witht the specified name.
038         * 
039         * @param name
040         *            the vector name
041         * @return the vector
042         */
043        public Vector get(String name);
044    
045        /**
046         * Returns the name of the column at <code>metadataIndex</code>. Note: this
047         * name needs to be unique; two columns in a meta data instance can not have
048         * the same name.
049         * 
050         * @param metadataIndex
051         *            the index of the column
052         * @return the name of the column
053         */
054        public String getColumnName(int metadataIndex);
055    
056        /**
057         * Returns the number of items that a vector in this instance contains.
058         * 
059         * @return the item count
060         */
061        public int getItemCount();
062    
063        /**
064         * Returns the number of columns in this meta data instance.
065         * 
066         * @return the number of columns.
067         */
068        public int getMetadataCount();
069    
070        /**
071         * Returns the column index for the given column name or <tt>-1</tt> if the
072         * name is not found.
073         * 
074         * @param columnName
075         *            the column name
076         * @return the column index
077         */
078        public int getColumnIndex(String columnName);
079    
080        /**
081         * Returns the value for the element at <code>itemIndex</code> and
082         * <code>metadataIndex</code>.
083         * 
084         * @param itemIndex
085         *            the item whose value is to be queried
086         * @param metadataIndex
087         *            the column name whose value is to be queried
088         * @return the value Object at the specified element.
089         */
090        public Object getValue(int itemIndex, int metadataIndex);
091    
092        /**
093         * Returns the value for the element at <code>metadataIndex</code> and
094         * <code>columnName</code>.
095         * 
096         * @param itemIndex
097         *            the item whose value is to be queried
098         * @param columnName
099         *            the column name whose value is to be queried
100         * @return the value Object at the specified element.
101         */
102        public Object getValue(int itemIndex, String columnName);
103    
104        /**
105         * Removes the column at the specified position in this meta data instance
106         * (optional operation). Shifts any subsequent columns to the left
107         * (subtracts one from their indices).
108         * 
109         * @param metadataIndex
110         *            the column index to remove.
111         * @throws UnsupportedOperationException
112         *             if the <tt>remove</tt> method is not supported by this list.
113         * @throws IndexOutOfBoundsException
114         *             if the index is out of range (metadataIndex &lt; 0 || index
115         *             &gt;= getColumnCount()).
116         */
117        public void remove(int metadataIndex);
118    
119        /**
120         * Sets the value in the cell at <code>columnName</code> and
121         * <code>itemIndex</code> to <code>aValue</code>.
122         * 
123         * @param aValue
124         *            the new value
125         * @param itemIndex
126         *            the item whose value is to be changed
127         * @param metadataIndex
128         *            the metadata index whose value is to be changed
129         * @see #getValue
130         */
131    
132        public void setValue(int itemIndex, int metadataIndex, Object aValue);
133    
134        /**
135         * Sets the value in the cell at <code>columnName</code> and
136         * <code>itemIndex</code> to <code>aValue</code>.
137         * 
138         * @param aValue
139         *            the new value
140         * @param itemIndex
141         *            the item whose value is to be changed
142         * @param columnName
143         *            the column name whose value is to be changed
144         * @see #getValue
145         */
146    
147        public void setValue(int itemIndex, String columnName, Object aValue);
148    }