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*/
020package org.olap4j.mdx;
021
022import 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 */
049public 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