001    /*
002    // $Id: IdentifierSegment.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.mdx;
021    
022    import java.util.List;
023    
024    /**
025     * Component in a compound identifier. It is described by its name and how
026     * the name is quoted.
027     *
028     * <p>For example, the identifier
029     * <code>[Store].USA.[New Mexico].&amp;[45]</code> has four segments:<ul>
030     * <li>"Store", {@link Quoting#QUOTED}</li>
031     * <li>"USA", {@link Quoting#UNQUOTED}</li>
032     * <li>"New Mexico", {@link Quoting#QUOTED}</li>
033     * <li>"45", {@link Quoting#KEY}</li>
034     * </ul>
035     *
036     * <p>QUOTED and UNQUOTED segments are represented using a
037     * {@link NameSegment NameSegment};
038     * KEY segments are represented using a
039     * {@link KeySegment KeySegment}.
040     *
041     * <p>To parse an identifier into a list of segments, use the method
042     * {@link org.olap4j.mdx.IdentifierNode#parseIdentifier(String)} and then call
043     * {@link org.olap4j.mdx.IdentifierNode#getSegmentList()} on the resulting
044     * node.</p>
045     *
046     * @version $Id: IdentifierSegment.java 482 2012-01-05 23:27:27Z jhyde $
047     * @author jhyde
048     */
049    public interface IdentifierSegment {
050    
051        /**
052         * Returns a string representation of this Segment.
053         *
054         * <p>For example, "[Foo]", "&amp;[123]", "Abc".
055         *
056         * @return String representation of this Segment
057         */
058        String toString();
059    
060        /**
061         * Appends a string representation of this Segment to a StringBuffer.
062         *
063         * @param buf StringBuffer
064         */
065        void toString(StringBuilder buf);
066    
067        /**
068         * Returns the region of the source code which this Segment was created
069         * from, if it was created by parsing.
070         *
071         * @return region of source code
072         */
073        ParseRegion getRegion();
074    
075        /**
076         * Returns how this Segment is quoted.
077         *
078         * @return how this Segment is quoted
079         */
080        Quoting getQuoting();
081    
082        /**
083         * Returns the name of this IdentifierSegment.
084         * Returns {@code null} if this IdentifierSegment represents a key.
085         *
086         * @return name of this Segment
087         */
088        String getName();
089    
090        /**
091         * Returns the key components, if this IdentifierSegment is a key. (That is,
092         * if {@link #getQuoting()} returns
093         * {@link Quoting#KEY}.)
094         *
095         * Returns null otherwise.
096         *
097         * @return Components of key, or null if this IdentifierSegment is not a key
098         */
099        List<NameSegment> getKeyParts();
100    }
101    
102    // End IdentifierSegment.java