SSL Token.java Sprache: JAVA

/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/

package org.netbeans.api.lexer;

import java.util.List;

/**
* Token describes a lexical element of input text.
* 
* It mainly provides an identification by {@link #id()}
* and a textual body (aka token's image) by {@link #text()}.
* 
* Only lexers should produce token instances and they should do it
* solely by using methods of {@link org.netbeans.spi.lexer.TokenFactory}.
*
* 
* Note:
* Do not create custom extensions of this class - lexers may only return
* implementations produced by <code>TokenFactory</code>.
* Creation of any other token implementations will be refused.
* 
* 
*
* 
* Token guarantees stability of the {@link #id()} and {@link #length()} methods.
* The {@link #hashCode()} and {@link #equals(Object)} methods
* use the default implementations from <code>java.lang.Object</code>.
* 
* The two tokens are only equal if they are the same object.
* 
*
* @author Miloslav Metelka
* @version 1.00
*/

public abstract class Token<T extends TokenId> {

 /**
 * Create token instance.
 * @throws IllegalStateException if a non-lexer-module-implementation token
 * is attempted to be created.
 */
 protected Token() {
 if (!(this instanceof org.netbeans.lib.lexer.token.AbstractToken)) {
 throw new IllegalStateException("Custom token implementations prohibited."); // NOI18N
 }
 }

 /**
 * Get identification of this token.
 *
 * @return non-null identification of this token.
 */
 public abstract T id();

 /**
 * Get text of this token (aka token's image) as a character sequence.
 * 
 * This text usually corresponds to the characters present in the lexed text input
 * unless {@link #isCustomText()} returns true.
 *
 * 
 * Note for mutable input sources:
 * 
 * This method should only be called
 * within a readonly (or read-write) transaction
 * over the underlying input source
 * (such as <code>javax.swing.text.Document.render()</code>
 * for Swing documents).
 * 
 * The result returned by this method
 * is only valid within a readonly (or read-write) transaction
 * over the input source (method must be re-called
 * during the next readonly transaction).
 * 
 *
 * @return non-null, non-empty text of this token.
 * It may be <code>null</code> in case the token was used
 * for a mutable input and it was removed
 * from the token list for the given input (but even in such case
 * the text can be retained in certain cases).
 *
 * 
 * The behavior of <code>equals()</code> and <code>hashCode()</code>
 * of the returned character sequence is generally undefined.
 * 
 * The returned character sequence can NOT be compared to another
 * character sequence by using its <code>equals()</code> method.
 * 
 * {@link org.netbeans.api.lexer.TokenUtilities} contains
 * utility methods related to token text comparing.
 * 
 *
 * 
 * The returned text is just a pointer to the primary source of the data
 * e.g. a swing document. The character data are not duplicated in the tokens.
 * 
 */
 public abstract CharSequence text();

 /**
 * Check whether {@link #text()} returns a custom value that may differ
 * from the original content of the text input.
 * 
 * Using custom text may be useful in case when only certain part of the token
 * is useful for the particular use and the token's text can be shrinked
 * and possibly a flyweight text can be used.
 * 
 * Also this is useful when using lexers generated by various lexer generators
 * that generally allow to use a custom text in the produced tokens.
 *
 * @return true if the text of the token does not correspond
 * to the original characters present in the text input being lexed.
 */
 public abstract boolean isCustomText();

 /**
 * Get number of characters in the original text input
 * that the token spans.
 * 
 * Usually this is the same value like {@link #text()}<code>.length()</code>
 * unless {@link #isCustomText()} returns true.
 * 
 * Also this method will return valid length in all cases even
 * when the text of the token could become <code>null</code>.
 *
 * @return >=0 length of the token.
 */
 public abstract int length();

 /**
 * Get the offset at which this token is present in the input
 * or <code>-1</code> if this token is flyweight (and therefore does not store offset).
 * 
 * Note: Use of {@link TokenSequence#offset()} is usually preferred over
 * this method because it returns actual offset even for the flyweight tokens.
 * 
 * If necessary the flyweight token may be replaced by regular token
 * by using {@link TokenSequence#offsetToken()}.
 *
 * 
 * The complexity of the method should generally be constant
 * regardless of the level of the language embedding.
 * 
 *
 * @param tokenHierarchy <code>null</code> should be passed
 * (the parameter is reserved for future use when token hierarchy snapshots will be implemented).
 *
 * @return >=0 offset of the token in the input or <code>-1</code>
 * if this token is flyweight.
 */
 public abstract int offset(TokenHierarchy<?> tokenHierarchy);

 /**
 * Checks whether this token instance is used for multiple occurrences
 * of this token in this or other inputs.
 * 
 * For example keywords or operators are typically flyweight tokens
 * while e.g. identifiers are not flyweight as their text generally varies.
 * 
 * Flyweight tokens may decrease the memory consumption for the tokens
 * considerably for frequently used tokens. For example a single space ' '
 * may be a useful flyweight token as it's used very often throughout a source.
 * The decision of what tokens are made flyweight is upon the implementor
 * of the particular language.
 *
 * 
 * If the token is flyweight its {@link #offset(TokenHierarchy)} returns -1.
 *
 * @return true if the token is flyweight or false otherwise.
 */
 public abstract boolean isFlyweight();

 /**
 * Check whether this token is no longer part of the token hierarchy.
 *
 * @return true if the token was removed from the token hierarchy
 * or false if it's still present in the hierarchy.
 * Flyweight tokens always return true from this method.
 */
 public boolean isRemoved() {
 throw new UnsupportedOperationException("Not implemented.");
 }

 /**
 * Check whether this token represents a complete token
 * or whether it's a particular part of a complete token.
 * 
 * Some lexers may also use this information to express an incomplete token.
 * For example an unclosed block comment at the end of java source
 * is represented as a BLOCK_COMMENT token id and {@link PartType#START}.
 *
 * @return {@link PartType#COMPLETE} for regular token or other part types
 * for particular token parts.
 */
 public abstract PartType partType();

 /**
 * Get a complete token that is joined from multiple parts (this token is one of those parts).
 *
 * @return complete token or null if this token is not a part of any token.
 */
 public Token<T> joinToken() {
 throw new UnsupportedOperationException("Not implemented.");
 }

 /**
 * Get all token parts comprising this token ordered from lowest to highest part's offset.
 * 
 * It's guaranteed that each token part is continuous in the input text
 * (there are no gaps inside the token part's text).
 * 
 * On the other hand there may be textual gaps between two adajcent token parts.
 *
 * @return list of token parts or null if the token is continuous.
 */
 public List<? extends Token<T>> joinedParts() {
 throw new UnsupportedOperationException("Not implemented.");
 }

 /**
 * Quickly determine whether this token has any extra properties.
 */
 public abstract boolean hasProperties();

 /**
 * Get extra property of this token.
 * 
 * The token properties are defined by the lexer upon token creation.
 * The clients of the API cannot set any property of the token.
 *
 * @param key non-null key of the property to get.
 * @return non-null value of the property or null if the property does not
 * have any value.
 *
 * @see #hasProperties()
 */
 public abstract Object getProperty(Object key);

 /**
 * Make sure the default implementation of <code>hashCode()</code> is used
 * and the token can safely be used in maps.
 */
 @Override
 public final int hashCode() {
 return super.hashCode();
 }

 /**
 * Make sure the default implementation of <code>equals()</code> is used
 * and the token can safely be used in maps.
 */
 @Override
 public final boolean equals(Object o) {
 return super.equals(o);
 }

}

quality100%

¤ Die Informationen auf dieser Webseite wurden nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit, noch Qualität der bereit gestellten Informationen zugesichert.0.28Bemerkung: (vorverarbeitet) ¤

Wurzel

Suchen

Beweissystem der NASA

Beweissystem Isabelle

NIST Cobol Testsuite

Cephes Mathematical Library

Wiener Entwicklungsmethode

Haftungshinweis

Die Informationen auf dieser Webseite wurden nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit, noch Qualität der bereit gestellten Informationen zugesichert.

Bemerkung:

Die farbliche Syntaxdarstellung ist noch experimentell.