javax.naming.directory
介面 Attribute

所有父級介面：

Cloneable, Serializable

所有已知實作類別：

BasicAttribute

public interface Attribute
extends Cloneable, Serializable

此介面表示與命名物件關聯的屬性。

在目錄中，命名的物件可以與其屬性關聯。Attribute 介面表示與命名物件關聯的屬性。屬性包含 0 個或多個（可能為 null 的）值。屬性值可以是有序的也可以是無序的（參閱 isOrdered()）。如果值是無序的，則不允許重複。如果值是有序的，則允許重複。

屬性的內容和表示形式及其值均由屬性的網要 定義。網要包含關於屬性語法和屬性其他性質的資訊。有關基礎目錄服務支持網要時如何獲取關於屬性的網要資訊的詳細資訊，請參閱 getAttributeDefinition() 和 getAttributeSyntaxDefinition()。

兩個屬性的相等性由實作類別確定。簡單的實作可以使用 Object.equals() 來確定屬性值的相等性，而較複雜的實作可能使用網要資訊來確定相等性。類似地，一個實作可能提供僅返回傳遞給其建構子的值的靜態存儲結構，另一個實作可能定義 get() 和 getAll() 從目錄動態獲取值。

注意，更新 Attribute（如添加或移除值）對目錄中相應的屬性表示形式沒有影響。只有使用 DirContext 介面中的操作才能實作對目錄的更新。

從以下版本開始：

1.3

另請參見：

BasicAttribute

欄位摘要

static long

serialVersionUID 使用 JNDI 1.1.1 中的 serialVersionUID 獲取互操作性。

方法摘要

void	add(int ix, Object attrVal) 將屬性值添加到屬性值的有序列表中。
boolean	add(Object attrVal) 向屬性添加新值。
void	clear() 從此屬性移除所有值。
Object	clone() 對屬性進行複製。
boolean	contains(Object attrVal) 確定某個值是否在屬性中。
Object	get() 檢索此屬性的其中一個值。
Object	get(int ix) 從屬性值的有序列表中檢索屬性值。
NamingEnumeration<?>	getAll() 檢索屬性值的列舉。
DirContext	getAttributeDefinition() 檢索屬性的網要定義。
DirContext	getAttributeSyntaxDefinition() 檢索與屬性關聯的語法定義。
String	getID() 檢索此屬性的 id。
boolean	isOrdered() 確定此屬性的值是否是有序的。
Object	remove(int ix) 從屬性值的有序列表中移除屬性值。
boolean	remove(Object attrval) 從屬性中移除指定值。
Object	set(int ix, Object attrVal) 設置屬性值的有序列表中的屬性值。
int	size() 檢索此屬性中的值數。

欄位詳細資訊

serialVersionUID

static final long serialVersionUID

使用 JNDI 1.1.1 中的 serialVersionUID 獲取互操作性。

另請參見：

常數欄位值

方法詳細資訊

getAll

NamingEnumeration<?> getAll()
                            throws NamingException

檢索屬性值的列舉。如果正在進行列舉時添加、更改或移除屬性值，則此列舉的行為是不確定的。如果屬性值是有序的，則列舉的項將是有序的。

返回：

屬性值的非 null 列舉。每個列舉元素都可能是一個 null 物件。物件的類別就是屬性值的類別。如果屬性值為 null，則元素為 null。如果屬性的值為零，則返回空列舉。

拋出：

NamingException - 如果檢索值時遇到命名異常。

另請參見：

isOrdered()

get

Object get()
           throws NamingException

檢索此屬性的其中一個值。如果屬性具有多個值並且是無序的，則返回其中的任意一個值。如果屬性具多個值並且是有序的，則返回第一個值。

返回：

表示屬性值之一的可能為 null 的物件。如果屬性值為 null，則返回 null。

拋出：

NamingException - 如果檢索值時遇到命名異常。

NoSuchElementException - 如果此屬性沒有值。

size

int size()

檢索此屬性中的值數。

返回：

此屬性中的非負值數。

getID

String getID()

檢索此屬性的 id。

返回：

此屬性的 id。它不能為 null。

contains

boolean contains(Object attrVal)

確定某個值是否在屬性中。相等性由實作確定，其可能使用 Object.equals() 或網要資訊來確定相等性。

參數：

attrVal - 要檢查的可能為 null 的值。如果為 null，則檢查屬性是否具有其值不為 null 的屬性值。

返回：

如果 attrVal 是此屬性的值之一，則返回 true；否則返回 false。

另請參見：

Object.equals(java.lang.Object), BasicAttribute.equals(java.lang.Object)

add

boolean add(Object attrVal)

向屬性添加新值。如果屬性值是無序的，並且 attrVal 已在屬性中，則此方法不執行任何操作。如果屬性值是有序的，則 attrVal 將被添加到屬性值列表的末尾。

相等性由實作確定，其可能使用 Object.equals() 或網要資訊來確定相等性。

參數：

attrVal - 要添加的可能為 null 的新值。如果為 null，則將 null 作為屬性值添加。

返回：

如果添加了值，則返回 true；否則返回 false。

remove

boolean remove(Object attrval)

從屬性中移除指定值。如果 attrval 不在屬性中，則此方法不執行任何操作。如果屬性值是有序的，則移除第一次出現的 attrVal，大於被移除值的索引處的屬性值朝列表頭方向上移（並將其索引減一）。

相等性由實作確定，其可能使用 Object.equals() 或網要資訊來確定相等性。

參數：

attrval - 要從此屬性中移除的可能為 null 的值。如果為 null，則移除為 null 的屬性值。

返回：

如果移除了值，則返回 true；否則返回 false。

clear

void clear()

從此屬性移除所有值。

getAttributeSyntaxDefinition

DirContext getAttributeSyntaxDefinition()
                                        throws NamingException

檢索與屬性關聯的語法定義。屬性的語法定義指定屬性值的格式。注意，這與作為 Java 物件的屬性值的表示形式不同。語法定義指的是目錄的語法 概念。

例如，即使值可能為 Java String 物件，其目錄語法仍可能為 "Printable String" 或 "Telephone Number"。或者值可能為位元組陣列，而其目錄語法為 "JPEG" 或 "Certificate"。例如，如果此屬性的語法為 "JPEG"，則此方法將返回 "JPEG" 的語法定義。

可以從語法定義檢索的資訊與目錄有關。

如果實作不支持網要，則其將拋出 OperationNotSupportedException。如果實作支持網要，則其應定義此方法以返回適當的資訊。

返回：

屬性的語法定義。如果實作支持網要但此特定屬性不具有任何網要資訊，則返回 null。

拋出：

OperationNotSupportedException - 如果不支持獲取網要。

NamingException - 如果在獲取網要時發生命名異常。

getAttributeDefinition

DirContext getAttributeDefinition()
                                  throws NamingException

檢索屬性的網要定義。屬性的網要定義包含的資訊有：屬性是多值的還是單值的；比較屬性值時使用哪些比對規則，等等。 可以從屬性定義檢索的資訊與目錄有關。

如果實作不支持網要，則其將拋出 OperationNotSupportedException。如果實作支持網要，則其應定義此方法以返回適當的資訊。

返回：

此屬性的網要定義。如果實作支持網要但此特定屬性不具有任何網要資訊，則返回 null。

拋出：

OperationNotSupportedException - 如果不支持獲取網要。

NamingException - 如果在獲取網要時發生命名異常。

clone

Object clone()

對屬性進行複製。副本包含與初始屬性相同的屬性值：這些屬性值不是其本身的副本。對副本的更改不會影響原件，反之亦然。

返回：

屬性的非 null 副本。

isOrdered

boolean isOrdered()

確定此屬性的值是否是有序的。如果屬性值是有序的，則允許重複的值。如果屬性值是無序的，則它們以任意順序出現，沒有重複值。

返回：

如果此屬性的值是有序的，則返回 true；否則返回 false。

另請參見：

get(int), remove(int), add(int, java.lang.Object), set(int, java.lang.Object)

get

Object get(int ix)
           throws NamingException

從屬性值的有序列表中檢索屬性值。此方法返回屬性值列表中 ix 索引處的值。如果屬性值是無序的，則此方法返回正好位於該索引處的值。

參數：

ix - 屬性值的有序列表中值的索引。0 <= ix < size()。

返回：

位於索引 ix 處的可能為 null 的屬性值；如果屬性值為 null，則返回 null。

拋出：

NamingException - 如果檢索值時遇到命名異常。

IndexOutOfBoundsException - 如果 ix 位於指定範圍之外。

remove

Object remove(int ix)

從屬性值的有序列表中移除屬性值。此方法移除屬性值列表中 ix 索引處的值。如果屬性值是無序的，則此方法移除正好位於該索引處的值。位於大於 ix 的索引處的值朝列表開頭上移（並且其索引減一）。

參數：

ix - 要移除的值的索引。0 <= ix < size()。

返回：

已移除的位於索引 ix 處的可能為 null 的屬性值；如果屬性值為 null，則返回 null。

拋出：

IndexOutOfBoundsException - 如果 ix 位於指定範圍之外。

add

void add(int ix,
         Object attrVal)

將屬性值添加到屬性值的有序列表中。此方法將 attrVal 添加到屬性值列表的索引 ix 處。位於 ix 處的索引的值或大於該處的索引的值朝列表的末尾下移（並且其索引加一）。如果屬性值是無序的並且已經具有 attrVal，則拋出 IllegalStateException。

參數：

ix - 要添加新值的屬性值的有序列表中的索引。0 <= ix <= size()。

attrVal - 要添加的可能為 null 的屬性值；如果為 null，則 null 即為添加的值。

拋出：

IndexOutOfBoundsException - 如果 ix 位於指定範圍之外。

IllegalStateException - 如果屬性值是無序的並且 attrVal 是這些值之一。

set

Object set(int ix,
           Object attrVal)

設置屬性值的有序列表中的屬性值。此方法將屬性值列表中 ix 索引處的值設置為 attrVal。移除舊值。如果屬性值是無序的，則此方法將正好位於該索引處的值設置為 attrVal，除非 attrVal 已經是這些值中的一個。若其已經是這些值中的一個，則拋出 IllegalStateException。

參數：

ix - 屬性值的有序列表中值的索引。0 <= ix < size()。

attrVal - 要使用的可能為 null 的屬性值。如果為 null，則 'null' 將替換舊值。

返回：

已替換的索引 ix 處的可能為 null 的屬性值。如果屬性值已為 null，則返回 null。

拋出：

IndexOutOfBoundsException - 如果 ix 位於指定範圍之外。

IllegalStateException - 如果 attrVal 已存在並且屬性值是無序的。