/*

 * Copyright (c) 2000, 2007, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package javax.management.openmbean;

// java import

//

import java.util.Set;

import java.util.Collection;

// jmx import

//

/**

 * which represent <i>tabular data</i> structures.

 *

 * @since 1.5

 */

public interface TabularData /*extends Map*/ {

    /* *** TabularData specific information methods *** */

    /**

     * Returns the <i>tabular type</i> describing this

     *

     * @return the tabular type.

     */

    public TabularType getTabularType();

    /**

     * composite data <var>value</var> parameter if it were added to this instance.

     * This method checks for the type validity of the specified <var>value</var>,

     *

     * @param  value                      the composite data value whose index in this

     *                                    must be of the same composite type as this instance's row type;

     *                                    must not be null.

     *

     *

     *

     *                                    row type definition.

     */

    public Object[] calculateIndex(CompositeData value) ;

    /* *** Content information query methods *** */

    /**

     * instance.

     *

     * @return the number of values contained.

     */

    public int size() ;

    /**

     * values (ie the number of rows) contained in this

     *

     */

    public boolean isEmpty() ;

    /**

     *

     *

     */

    public boolean containsKey(Object[] key) ;

    /**

     *

     *

     */

    public boolean containsValue(CompositeData value) ;

    /**

     *

     * @param key the key of the row to return.

     *

     * @return the value corresponding to <var>key</var>.

     *

     * @throws NullPointerException if the <var>key</var> is

     * @throws InvalidKeyException if the <var>key</var> does not

     */

    public CompositeData get(Object[] key) ;

    /* *** Content modification operations (one element at a time) *** */

    /**

     * The composite type of <var>value</var> must be the same as this

     * instance's row type (ie the composite type returned by

     * same as the one calculated for the <var>value</var> to be

     * added. The index for <var>value</var> is calculated according

     *

     *                                    must be of the same composite type as this instance's row type;

     *                                    must not be null.

     *

     *                                    row type definition.

     * @throws KeyAlreadyExistsException  if the index for <var>value</var>, calculated according to

     *                                    already maps to an existing value in the underlying HashMap.

     */

    public void put(CompositeData value) ;

    /**

     *

     *              must not be null.

     *

     *         if there was no mapping for key.

     *

     */

    public CompositeData remove(Object[] key) ;

    /* ***   Content modification bulk operations   *** */

    /**

     *

     *

     * @throws InvalidOpenTypeException   if an element of <var>values</var> does not conform to

     * @throws KeyAlreadyExistsException  if the index for an element of <var>values</var>, calculated according to

     *                                    already maps to an existing value in this instance,

     *                                    or two elements of <var>values</var> have the same index.

     */

    public void putAll(CompositeData[] values) ;

    /**

     */

    public void clear();

    /* ***   Collection views of the keys and values   *** */

    /**

     * Returns a set view of the keys (ie the index values) of the

     * {@code CompositeData} values (ie the rows) contained in this

     * {@code TabularData} instance. The returned {@code Set} is a

     * {@code Set<List<?>>} but is declared as a {@code Set<?>} for

     * compatibility reasons. The returned set can be used to iterate

     * over the keys.

     *

     * @return a set view ({@code Set<List<?>>}) of the index values

     * used in this {@code TabularData} instance.

     */

    public Set<?> keySet();

    /**

     * Returns a collection view of the {@code CompositeData} values

     * (ie the rows) contained in this {@code TabularData} instance.

     * The returned {@code Collection} is a {@code Collection<CompositeData>}

     * but is declared as a {@code Collection<?>} for compatibility reasons.

     * The returned collection can be used to iterate over the values.

     *

     * @return a collection view ({@code Collection<CompositeData>})

     * of the rows contained in this {@code TabularData} instance.

     */

    public Collection<?> values();

    /* ***  Commodity methods from java.lang.Object  *** */

    /**

     * <p>

     * <ul>

     * <li><var>obj</var> is non null,</li>

     * <li>their row types are equal</li>

     * <li>their contents (ie index to value mappings) are equal</li>

     * </ul>

     * <br>&nbsp;

     *

     */

    public boolean equals(Object obj);

    /**

     * <p>

     * (ie: its <i>tabular type</i> and its content, where the content is defined as all the index to value mappings).

     * <p>

     * as required by the general contract of the method

     * {@link Object#hashCode() Object.hashCode()}.

     *

     */

    public int hashCode();

    /**

     * <p>

     * The string representation consists of the name of the implementing class,

     * and the tabular type of this instance.

     *

     */

    public String toString();

}