CatalogLookupName (General SQL Parser Java Library Core 4.2.19 API)

Object
- gudusoft.gsqlparser.catalog.runtime.CatalogLookupName

```
public final class CatalogLookupName
extends Object
```
A request to find a catalog object — explicitly NOT an identity (stage S0R of docs/refactor/identifier_identity_display_separation_plan.md).
Why a lookup is a different type from a key
t, s.t and db..t are all normal things to write, and none of them is a complete identity: the first two leave levels unstated, and the third states that a level was written but left empty. Only after defaults and the search path supply the missing context does a CatalogObjectKey exist. Collapsing the two ideas into one type is what let db..t be keyed as db.dbo.t, which silently binds the wrong object whenever the session default schema is not dbo.
Three states, never two
- CatalogLookupName.SlotState.ABSENT — the dialect or declared layout genuinely has no such level. MySQL has no schema level; there is nothing missing.
- CatalogLookupName.SlotState.OMITTED — the level EXISTS and the caller did not name it. db..t omits its schema; a bare t omits both. A resolver must supply it before an identity can be built, and CatalogObjectKey refuses to contain one.
- CatalogLookupName.SlotState.PRESENT — named, with its text and the provenance of that text.
Conflating ABSENT with OMITTED loses the only signal that tells "this dialect has no schemas" apart from "the user did not say which schema", and an empty string conflates both with a level named by the empty name.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`CatalogLookupName.Builder`
`static class`	`CatalogLookupName.Slot` One level of the request.
`static class`	`CatalogLookupName.SlotState` Whether a hierarchy level is inapplicable, unstated, or named.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static CatalogLookupName.Builder`	`builder(CatalogHierarchy hierarchy)` A request against a declared namespace topology.
`String`	`getDatabaseLink()`
`IdentifierInputForm`	`getDatabaseLinkForm()`
`CatalogHierarchy`	`getHierarchy()` The declared namespace topology this request was built against.
`List<CatalogLookupName.Slot>`	`getObjectSlots()` Every object slot, outermost first.
`CatalogParentConstraint`	`getParentConstraint()` What is known about the parent's kind, or null when the request names no child.
`CatalogLookupName.Slot`	`getParentObjectSlot()` The object slot that contains the terminal, or null when the terminal has no object parent.
`List<CatalogLookupName.Slot>`	`getSlots()` The slots, outermost first.
`CatalogObjectKind`	`getTerminalKind()`
`CatalogLookupName.Slot`	`getTerminalSlot()` The innermost slot — what this request is actually looking for.
`boolean`	`isFullyQualified()` Whether every level this request needs is named, so an identity could be built without consulting any default.
`static CatalogLookupName`	`ofDeclaredLayout(List<String> components, CatalogNameLayout layout, IdentifierInputForm form, CatalogObjectKind terminalKind, CatalogHierarchy hierarchy)` Parses a FLAT name under a layout the caller DECLARES, against a topology the caller DECLARES.
`CatalogLookupName.Slot`	`slotOf(IdentifierComponentRole role)` The slot for a role, or null when this request has no such level.
`String`	`toString()`

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Method Detail
  - builder
```
public static CatalogLookupName.Builder builder(CatalogHierarchy hierarchy)
```
    A request against a declared namespace topology. The topology is required: whether a missing schema is an OMISSION or simply inapplicable is what it answers, and no component list can.
  - ofDeclaredLayout
```
public static CatalogLookupName ofDeclaredLayout(List<String> components,
                                                 CatalogNameLayout layout,
                                                 IdentifierInputForm form,
                                                 CatalogObjectKind terminalKind,
                                                 CatalogHierarchy hierarchy)
```
    Parses a FLAT name under a layout the caller DECLARES, against a topology the caller DECLARES. The parser verifies the component count against the layout and refuses otherwise; it never chooses the layout, which is the whole point — choosing is the defect.
    Where the layout has a container OBJECT whose exact kind a flat name cannot carry — a column's parent may be a table, a view or a materialized view — the FAMILY is recorded instead, derived from the layout itself. A lookup legitimately knows only the family; only a resolved CatalogObjectKey carries the exact kind.
    Prefer builder(CatalogHierarchy) with the parts passed separately. This exists for callers whose input genuinely is one string.
    
    Throws:
    
    IllegalArgumentException - if the component count does not match the declared layout
  - getSlots
```
public List<CatalogLookupName.Slot> getSlots()
```
    The slots, outermost first.
  - getTerminalKind
```
public CatalogObjectKind getTerminalKind()
```
  - getHierarchy
```
public CatalogHierarchy getHierarchy()
```
    The declared namespace topology this request was built against.
  - getParentConstraint
```
public CatalogParentConstraint getParentConstraint()
```
    What is known about the parent's kind, or null when the request names no child.
  - getDatabaseLink
```
public String getDatabaseLink()
```
  - getDatabaseLinkForm
```
public IdentifierInputForm getDatabaseLinkForm()
```
  - isFullyQualified
```
public boolean isFullyQualified()
```
    Whether every level this request needs is named, so an identity could be built without consulting any default. An omission here is not an error — it is the normal reason a resolver is involved.
  - slotOf
```
public CatalogLookupName.Slot slotOf(IdentifierComponentRole role)
```
    The slot for a role, or null when this request has no such level.
    
    Throws:
    
    IllegalArgumentException - for IdentifierComponentRole.OBJECT, which may appear twice — a relation and its index. Returning the first silently would hand a caller asking for "the object" the container when it wanted the child. Use getTerminalSlot(), getParentObjectSlot() or getObjectSlots().
  - getTerminalSlot
```
public CatalogLookupName.Slot getTerminalSlot()
```
    The innermost slot — what this request is actually looking for.
  - getParentObjectSlot
```
public CatalogLookupName.Slot getParentObjectSlot()
```
    The object slot that contains the terminal, or null when the terminal has no object parent.
  - getObjectSlots
```
public List<CatalogLookupName.Slot> getObjectSlots()
```
    Every object slot, outermost first.
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class CatalogLookupName

Why a lookup is a different type from a key

Three states, never two

Nested Class Summary

Method Summary

Methods inherited from class Object

Method Detail

builder

ofDeclaredLayout

getSlots

getTerminalKind

getHierarchy

getParentConstraint

getDatabaseLink

getDatabaseLinkForm

isFullyQualified

slotOf

getTerminalSlot

getParentObjectSlot

getObjectSlots

toString