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    */
020    package 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     */
029    public 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