Top Description Fields Constructors Methods
org.jboss.jandex

public final Class DotName

extends Object
implements Comparable<DotName>
Class Inheritance
All Implemented Interfaces
java.lang.Comparable
A DotName represents a dot separated name, typically a Java package or a Java class. It has two possible variants. A simple wrapper based variant allows for fast construction (it simply wraps the specified name string). Whereas, a componentized variant represents one or more String components that, when combined with a dot character, assemble the full name. The intention of the componentized variant is that the String components can be reused to offer memory efficiency. This reuse is common in Java where packages and classes follow a tree structure.

Both the simple and componentized variants are considered semantically equivalent if they refer to the same logical name. More specifically, the equals and hashCode methods return the same values for the same semantic name regardless of the variant used. Which variant to use when depends on the specific performance and overhead objectives of the specific use pattern.

Simple names are cheap to construct (just an additional wrapper object), so are ideal for temporary use, like looking for an entry in a Map. Componentized names however require that they be split in advance, and so require some additional time to construct. However, the memory benefits of reusing component strings make them desirable when stored in a longer term area such as in a Java data structure.

Author
Jason T. Greene

Field Summary

Modifier and TypeField and Description
private final boolean
componentized

public static final DotName
ENUM_NAME

private int
hash

private final boolean
innerClass

pack-priv static final DotName
JAVA_LANG_ANNOTATION_NAME

pack-priv static final DotName
JAVA_LANG_NAME

pack-priv static final DotName
JAVA_NAME

private final String
local

public static final DotName
OBJECT_NAME

private final DotName
prefix

public static final DotName
RECORD_NAME

public static final DotName
STRING_NAME

Constructor Summary

AccessConstructor and Description
pack-priv
DotName(DotName prefix, String local, boolean noDots, boolean innerClass)

Method Summary

Modifier and TypeMethod and Description
private void
buildString(char delim, StringBuilder builder)

public int

Returns:

a negative number if this is less than the specified object, a positive if greater, and zero if equal
compareTo(DotName
the DotName to compare to
other)

Implements java.lang.Comparable.compareTo.

Compares a DotName to another DotName and returns whether this DotName is lesser than, greater than, or equal to the specified DotName.
private static int
componentizedCompare(DotName[] a, DotName[] b)

private static boolean
componentizedEquals(DotName a, DotName b)

public static DotName

Returns:

a componentized DotName; never null
createComponentized(DotName
another DotName that is the portion of the final name to the left of localName; may be null if there is no prefix
prefix, String
the local portion of this name; must not be null and must not contain '.'
localName)

Constructs a componentized DotName.

public static DotName

Returns:

a componentized DotName; never null
createComponentized(DotName
another DotName that is the portion of the final name to the left of localName; may be null if there is no prefix
prefix, String
the local portion of this name; must not be null and must not contain '.'
localName, boolean
whether the localName is an inner class style name, which is joined to the prefix using '$' instead of '.'
innerClass)

Constructs a componentized DotName.

public static DotName

Returns:

a simple DotName that wraps given name; never null
createSimple(String
a fully qualified name (with dots); must not be null
name)

Constructs a simple DotName which stores the string in its entirety.

public static DotName

Returns:

a simple DotName that wraps the name of given clazz; never null
createSimple(Class<?>
a class whose fully qualified name is returned; must not be null
clazz)

Constructs a simple DotName which stores the name of given class in its entirety.

public boolean

Returns:

true if equal, false if not
equals(Object
the DotName object to compare to
o)

Overrides java.lang.Object.equals.

Compares a DotName to another DotName and returns true if they represent the same underlying semantic name.
private static DotName[]
flatten(DotName name)

public int

Returns:

a hash code representing this object
hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code which is based on the semantic representation of this DotName.
public boolean

Returns:

true if it is componentized, false if it is a simple DotName
isComponentized()

Returns whether this DotName is a componentized variant.

public boolean

Returns:

true if local is an inner class style delimited name, false otherwise
isInner()

Returns whether the local portion of a componentized DotName is separated by an inner class style delimiter ('$').

public String

Returns:

the local portion of this DotName; never null
local()

Returns the local portion of this DotName.

public String

Returns:

the package name or null if this DotName has no package prefix
packagePrefix()

Returns the package portion of this DotName.

public DotName

Returns:

the package name or null if this DotName has no package prefix
packagePrefixName()

Returns the package portion of this DotName.

public DotName

Returns:

the parent prefix for this DotName; may be null
prefix()

Returns the parent prefix for this DotName or null if there is none.

private void
stripPackage(StringBuilder builder)

public String

Returns:

the binary class name
toString()

Overrides java.lang.Object.toString.

Returns the regular binary class name.
public String

Returns:

the binary class name with given character used as a package separator
toString(char
the package separator; typically ., but may be e.g. / to construct a bytecode descriptor
delim)

Returns the regular binary class name where delim is used as a package separator.

public String

Returns:

the portion of the fully qualified name that does not include a package name
withoutPackagePrefix()

Returns the portion of this DotName that does not contain a package prefix.

Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAllwaitwaitwait

Field Detail

componentizedback to summary
private final boolean componentized
ENUM_NAMEback to summary
public static final DotName ENUM_NAME
hashback to summary
private int hash
innerClassback to summary
private final boolean innerClass
JAVA_LANG_ANNOTATION_NAMEback to summary
pack-priv static final DotName JAVA_LANG_ANNOTATION_NAME
JAVA_LANG_NAMEback to summary
pack-priv static final DotName JAVA_LANG_NAME
JAVA_NAMEback to summary
pack-priv static final DotName JAVA_NAME
localback to summary
private final String local
OBJECT_NAMEback to summary
public static final DotName OBJECT_NAME
prefixback to summary
private final DotName prefix
RECORD_NAMEback to summary
public static final DotName RECORD_NAME
STRING_NAMEback to summary
public static final DotName STRING_NAME

Constructor Detail

DotNameback to summary
pack-priv DotName(DotName prefix, String local, boolean noDots, boolean innerClass)

Method Detail

buildStringback to summary
private void buildString(char delim, StringBuilder builder)
compareToback to summary
public int compareTo(DotName other)

Implements java.lang.Comparable.compareTo.

Compares a DotName to another DotName and returns whether this DotName is lesser than, greater than, or equal to the specified DotName. If this DotName is lesser, a negative value is returned. If greater, a positive value is returned. If equal, zero is returned.

Parameters
other:DotName

the DotName to compare to

Returns:int

a negative number if this is less than the specified object, a positive if greater, and zero if equal

Annotations
@Override
See Also
Comparable#compareTo(Object)
componentizedCompareback to summary
private static int componentizedCompare(DotName[] a, DotName[] b)
componentizedEqualsback to summary
private static boolean componentizedEquals(DotName a, DotName b)
createComponentizedback to summary
public static DotName createComponentized(DotName prefix, String localName)

Constructs a componentized DotName. Such DotName refers to a parent prefix (or null if there is no further prefix) in addition to a local name that has no dot separator. The fully qualified name this DotName represents is constructed by recursing all parent prefixes and joining all local names with the '.' character.

Parameters
prefix:DotName

another DotName that is the portion of the final name to the left of localName; may be null if there is no prefix

localName:String

the local portion of this name; must not be null and must not contain '.'

Returns:DotName

a componentized DotName; never null

createComponentizedback to summary
public static DotName createComponentized(DotName prefix, String localName, boolean innerClass)

Constructs a componentized DotName. Such DotName refers to a parent prefix (or null if there is no further prefix) in addition to a local name that has no dot separator. The fully qualified name this DotName represents is constructed by recursing all parent prefixes and joining all local names with the '.' character.

Parameters
prefix:DotName

another DotName that is the portion of the final name to the left of localName; may be null if there is no prefix

localName:String

the local portion of this name; must not be null and must not contain '.'

innerClass:boolean

whether the localName is an inner class style name, which is joined to the prefix using '$' instead of '.'

Returns:DotName

a componentized DotName; never null

createSimpleback to summary
public static DotName createSimple(String name)

Constructs a simple DotName which stores the string in its entirety. This variant is ideal for temporary usage, such as looking up an entry in a Map or an index.

Parameters
name:String

a fully qualified name (with dots); must not be null

Returns:DotName

a simple DotName that wraps given name; never null

createSimpleback to summary
public static DotName createSimple(Class<?> clazz)

Constructs a simple DotName which stores the name of given class in its entirety. This variant is ideal for temporary usage, such as looking up an entry in a Map or an index.

This method is a shortcut for DotName.createSimple(clazz.getName()).

Parameters
clazz:Class<?>

a class whose fully qualified name is returned; must not be null

Returns:DotName

a simple DotName that wraps the name of given clazz; never null

equalsback to summary
public boolean equals(Object o)

Overrides java.lang.Object.equals.

Compares a DotName to another DotName and returns true if they represent the same underlying semantic name. In other words, whether a name is componentized or simple has no bearing on the comparison.

Parameters
o:Object

the DotName object to compare to

Returns:boolean

true if equal, false if not

See Also
Object#equals(Object)
flattenback to summary
private static DotName[] flatten(DotName name)
hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code which is based on the semantic representation of this DotName.

Whether a DotName is componentized has no impact on the calculated hash code. In other words, a componentized DotName and a simple DotName that represent the same fully qualified name have the same hash code.

Returns:int

a hash code representing this object

See Also
Object#hashCode()
isComponentizedback to summary
public boolean isComponentized()

Returns whether this DotName is a componentized variant.

Returns:boolean

true if it is componentized, false if it is a simple DotName

isInnerback to summary
public boolean isInner()

Returns whether the local portion of a componentized DotName is separated by an inner class style delimiter ('$'). The result is undefined when this DotName is not componentized.

This should not be used to test whether the name truly refers to an inner class, only that the dollar sign delimits the value. Java class names are allowed to contain '$' signs, so the local value could simply be a fragment of a class name, and not an actual inner class. The correct way to determine whether a name refers to an actual inner class is to look up a ClassInfo in the index and examine the nesting type like so: 

index.getClassByName(name).nestingType() != TOP_LEVEL;
Returns:boolean

true if local is an inner class style delimited name, false otherwise

localback to summary
public String local()

Returns the local portion of this DotName. In simple variants, the entire fully qualified string is returned. In componentized variants, just the rightmost portion not including a separator (either '.' or '$') is returned.

Use withoutPackagePrefix() instead of this method if the desired value is the part of the string (including '$' signs if present) after the rightmost '.' delimiter.

Returns:String

the local portion of this DotName; never null

packagePrefixback to summary
public String packagePrefix()

Returns the package portion of this DotName.

Returns:String

the package name or null if this DotName has no package prefix

Since
2.4
packagePrefixNameback to summary
public DotName packagePrefixName()

Returns the package portion of this DotName. This is a DotName-returning variant of packagePrefix().

Returns:DotName

the package name or null if this DotName has no package prefix

Since
3.0
prefixback to summary
public DotName prefix()

Returns the parent prefix for this DotName or null if there is none. Simple DotName variants never have a prefix.

Returns:DotName

the parent prefix for this DotName; may be null

stripPackageback to summary
private void stripPackage(StringBuilder builder)
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Returns the regular binary class name.

Returns:String

the binary class name

toStringback to summary
public String toString(char delim)

Returns the regular binary class name where delim is used as a package separator.

Parameters
delim:char

the package separator; typically ., but may be e.g. / to construct a bytecode descriptor

Returns:String

the binary class name with given character used as a package separator

withoutPackagePrefixback to summary
public String withoutPackagePrefix()

Returns the portion of this DotName that does not contain a package prefix. In the case of an inner class syntax name, the '$' portion is included in the return value.

Returns:String

the portion of the fully qualified name that does not include a package name

Since
2.1.1