001/*
002// $Id: MetadataElement.java 482 2012-01-05 23:27:27Z jhyde $
003//
004// Licensed to Julian Hyde under one or more contributor license
005// agreements. See the NOTICE file distributed with this work for
006// additional information regarding copyright ownership.
007//
008// Julian Hyde licenses this file to you under the Apache License,
009// Version 2.0 (the "License"); you may not use this file except in
010// compliance with the License. You may obtain a copy of the License at:
011//
012// http://www.apache.org/licenses/LICENSE-2.0
013//
014// Unless required by applicable law or agreed to in writing, software
015// distributed under the License is distributed on an "AS IS" BASIS,
016// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017// See the License for the specific language governing permissions and
018// limitations under the License.
019*/
020package org.olap4j.metadata;
021
022/**
023 * An element which describes the structure of an OLAP schema.
024 *
025 * @author jhyde
026 * @version $Id: MetadataElement.java 482 2012-01-05 23:27:27Z jhyde $
027 * @since Oct 13, 2006
028 */
029public interface MetadataElement {
030    /**
031     * Returns the name of this element.
032     *
033     * <p>Name is never null. Unlike {@link #getCaption() caption} and
034     * {@link #getDescription() description}, an element's name is the same in
035     * every {@link java.util.Locale}.
036     *
037     * @return name of this element
038     */
039    String getName();
040
041    /**
042     * Returns the unique name of this element within its schema.
043     *
044     * <p>The unique name is never null, and is unique among all elements in
045     * this {@link Schema}.
046     *
047     * <p>Unlike {@link #getCaption() caption} and
048     * {@link #getDescription() description}, an element's unique name is the
049     * same in every {@link java.util.Locale}.
050     *
051     * <p>The structure of the unique name is provider-specific and subject to
052     * change between provider versions. Applications should not attempt to
053     * reverse-engineer the structure of the name.
054     *
055     * @return unique name of this element
056     */
057    String getUniqueName();
058
059    /**
060     * Returns the caption of this element in the current connection's
061     * {@link java.util.Locale}.
062     *
063     * <p>This method may return the empty string, but never returns null.
064     * The rules for deriving an element's caption are provider-specific,
065     * but generally if no caption is defined for the element in a given locale,
066     * returns the name of the element.</p>
067     *
068     * @return caption of this element in the current locale; never null.
069     *
070     * @see org.olap4j.OlapConnection#getLocale()
071     */
072    String getCaption();
073
074    /**
075     * Returns the description of this element in the current connection's
076     * {@link java.util.Locale}.
077     *
078     * <p>This method may return the empty string, but never returns null.
079     * The rules for deriving an element's description are provider-specific,
080     * but generally if no description is defined
081     * for the element in a given locale, returns the description in base
082     * locale.</p>
083     *
084     * @return description of this element in the current locale; never null.
085     *
086     * @see org.olap4j.OlapConnection#getLocale()
087     */
088    String getDescription();
089
090    /**
091     * Returns whether this element is visible to end-users.
092     *
093     * <p>Visibility is a hint for client applications. An element's visibility
094     * does not affect how it is treated when MDX queries are evaluated.
095     *
096     * <p>If you wish to hide an MDX element at a deeper level, consider two
097     * OLAP concepts that sound similar to visibility but have different
098     * semantics:
099     *
100     * <ul>
101     * <li>{@link Member#isHidden Hidden members} in ragged hierarchies;</li>
102     * <li>{@link org.olap4j.OlapConnection#getRoleName Access control}</li>
103     * </ul>
104     *
105     * @return Whether this element is visible
106     */
107    boolean isVisible();
108}
109
110// End MetadataElement.java