Класс IIOMetadata

java.lang.Object

javax.imageio.metadata.IIOMetadata

public abstract class IIOMetadata extends Object

Абстрактный класс, который должен быть расширен объектами, представляющими метаданные (данные, не являющиеся изображением), связанные с изображениями и потоками. Плагины представляют метаданные с помощью непрозрачных, специфичных для плагина объектов. Однако эти объекты предоставляют возможность доступа к их внутренней информации как к дереву IIOMetadataNode объектов, поддерживающих интерфейсы XML DOM, а также дополнительные интерфейсы для хранения нетекстовых данных и извлечения информации о допустимых значениях данных. Формат таких деревьев зависит от плагина, но плагины могут выбрать поддержку нейтрального для плагина формата, описанного ниже. Один плагин может поддерживать несколько форматов метаданных, имена которых можно определить, вызвав getMetadataFormatNames. Плагин также может поддерживать один специальный формат, называемый «родным» форматом, который предназначен для бескомпромиссного кодирования своих метаданных. Этот формат обычно будет разработан специально для работы с определённым форматом файла, так что изображения могут быть загружены и сохранены в том же формате без потери метаданных, но может быть менее полезным для передачи метаданных между ImageReader и ImageWriter для разных форматов изображений. Для преобразования между двумя родными форматами настолько без потерь, насколько это позволяют форматы файлов изображений, необходимо использовать объект ImageTranscoder.

См. также:

Краткое описание полей

Модификатор и тип	Поле	Описание
`protected IIOMetadataController`	`controller`	The `IIOMetadataController` that will be used to provide settings for this `IIOMetadata` object when the `activateController` method is called.
`protected IIOMetadataController`	`defaultController`	An `IIOMetadataController` that is suggested for use as the controller for this `IIOMetadata` object.
`protected String[]`	`extraMetadataFormatClassNames`	An array of names of classes implementing `IIOMetadataFormat` and representing the metadata formats, other than the standard and native formats, that are supported by this plug-in, initialized to `null` and set via the constructor.
`protected String[]`	`extraMetadataFormatNames`	An array of names of formats, other than the standard and native formats, that are supported by this plug-in, initialized to `null` and set via the constructor.
`protected String`	`nativeMetadataFormatClassName`	The name of the class implementing `IIOMetadataFormat` and representing the native metadata format, initialized to `null` and set via the constructor.
`protected String`	`nativeMetadataFormatName`	The name of the native metadata format for this object, initialized to `null` and set via the constructor.
`protected boolean`	`standardFormatSupported`	A boolean indicating whether the concrete subclass supports the standard metadata format, set via the constructor.

Краткое описание конструкторов

IIOMetadata()

IIOMetadata(boolean standardMetadataFormatSupported,
 String nativeMetadataFormatName,
 String nativeMetadataFormatClassName,
 String[] extraMetadataFormatNames,
 String[] extraMetadataFormatClassNames)

Модификатор	Конструктор	Описание
`protected`	Constructs an empty `IIOMetadata` object.
`protected`	Constructs an `IIOMetadata` object with the given format names and format class names, as well as a boolean indicating whether the standard format is supported.

Краткое описание методов

Модификатор и тип	Метод	Описание
`boolean`	`activateController()`	Activates the installed `IIOMetadataController` for this `IIOMetadata` object and returns the resulting value.
`abstract Node`	`getAsTree(String formatName)`	Returns an XML DOM `Node` object that represents the root of a tree of metadata contained within this object according to the conventions defined by a given metadata format.
`IIOMetadataController`	`getController()`	Returns whatever `IIOMetadataController` is currently installed.
`IIOMetadataController`	`getDefaultController()`	Returns the default `IIOMetadataController`, if there is one, regardless of the currently installed controller.
`String[]`	`getExtraMetadataFormatNames()`	Returns an array of `String`s containing the names of additional metadata formats, other than the native and standard formats, recognized by this plug-in's `getAsTree`, `setFromTree`, and `mergeTree` methods.
`IIOMetadataFormat`	`getMetadataFormat(String formatName)`	Returns an `IIOMetadataFormat` object describing the given metadata format, or `null` if no description is available.
`String[]`	`getMetadataFormatNames()`	Returns an array of `String`s containing the names of all metadata formats, including the native and standard formats, recognized by this plug-in's `getAsTree`, `setFromTree`, and `mergeTree` methods.
`String`	`getNativeMetadataFormatName()`	Returns the name of the "native" metadata format for this plug-in, which typically allows for lossless encoding and transmission of the metadata stored in the format handled by this plug-in.
`protected IIOMetadataNode`	`getStandardChromaNode()`	Returns an `IIOMetadataNode` representing the chroma information of the standard `javax_imageio_1.0` metadata format, or `null` if no such information is available.
`protected IIOMetadataNode`	`getStandardCompressionNode()`	Returns an `IIOMetadataNode` representing the compression information of the standard `javax_imageio_1.0` metadata format, or `null` if no such information is available.
`protected IIOMetadataNode`	`getStandardDataNode()`	Returns an `IIOMetadataNode` representing the data format information of the standard `javax_imageio_1.0` metadata format, or `null` if no such information is available.
`protected IIOMetadataNode`	`getStandardDimensionNode()`	Returns an `IIOMetadataNode` representing the dimension information of the standard `javax_imageio_1.0` metadata format, or `null` if no such information is available.
`protected IIOMetadataNode`	`getStandardDocumentNode()`	Returns an `IIOMetadataNode` representing the document information of the standard `javax_imageio_1.0` metadata format, or `null` if no such information is available.
`protected IIOMetadataNode`	`getStandardTextNode()`	Returns an `IIOMetadataNode` representing the textual information of the standard `javax_imageio_1.0` metadata format, or `null` if no such information is available.
`protected IIOMetadataNode`	`getStandardTileNode()`	Returns an `IIOMetadataNode` representing the tiling information of the standard `javax_imageio_1.0` metadata format, or `null` if no such information is available.
`protected IIOMetadataNode`	`getStandardTransparencyNode()`	Returns an `IIOMetadataNode` representing the transparency information of the standard `javax_imageio_1.0` metadata format, or `null` if no such information is available.
`protected final IIOMetadataNode`	`getStandardTree()`	A utility method to return a tree of `IIOMetadataNode`s representing the metadata contained within this object according to the conventions of the standard `javax_imageio_1.0` metadata format.
`boolean`	`hasController()`	Returns `true` if there is a controller installed for this `IIOMetadata` object.
`abstract boolean`	`isReadOnly()`	Returns `true` if this object does not support the `mergeTree`, `setFromTree`, and `reset` methods.
`boolean`	`isStandardMetadataFormatSupported()`	Returns `true` if the standard metadata format is supported by `getMetadataFormat`, `getAsTree`, `setFromTree`, and `mergeTree`.
`abstract void`	`mergeTree(String formatName, Node root)`	Alters the internal state of this `IIOMetadata` object from a tree of XML DOM `Node`s whose syntax is defined by the given metadata format.
`abstract void`	`reset()`	Resets all the data stored in this object to default values, usually to the state this object was in immediately after construction, though the precise semantics are plug-in specific.
`void`	`setController(IIOMetadataController controller)`	Sets the `IIOMetadataController` to be used to provide settings for this `IIOMetadata` object when the `activateController` method is called, overriding any default controller.
`void`	`setFromTree(String formatName, Node root)`	Sets the internal state of this `IIOMetadata` object from a tree of XML DOM `Node`s whose syntax is defined by the given metadata format.

Методы, объявленные в классе java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Подробное описание полей

standardFormatSupported

protected boolean standardFormatSupported

Логическое значение, указывающее, поддерживает ли конкретный подкласс стандартный формат метаданных, устанавливается через конструктор.

nativeMetadataFormatName

protected String nativeMetadataFormatName

Имя нативного формата метаданных для этого объекта, инициализируется значением null и устанавливается через конструктор.

nativeMetadataFormatClassName

protected String nativeMetadataFormatClassName

Имя класса, реализующего IIOMetadataFormat и представляющего нативный формат метаданных, инициализируется значением null и устанавливается через конструктор.

extraMetadataFormatNames

protected String[] extraMetadataFormatNames

Массив имён форматов, помимо стандартного и нативного, поддерживаемых этим плагином, инициализируется значением null и устанавливается через конструктор.

extraMetadataFormatClassNames

protected String[] extraMetadataFormatClassNames

Массив имён классов, реализующих IIOMetadataFormat и представляющих форматы метаданных, помимо стандартного и нативного, поддерживаемые этим плагином, инициализируется значением null и устанавливается через конструктор.

defaultController

protected IIOMetadataController defaultController

Рекомендуемый IIOMetadataController для использования в качестве контроллера для этого объекта IIOMetadata. Его можно получить через getDefaultController. Для установки контроллера по умолчанию, вызовите setController(getDefaultController()). Эта переменная-член должна устанавливаться подклассами, которые выбирают предоставление собственного контроллера по умолчанию, обычно графического интерфейса, для настройки параметров.

См. также:

controller

protected IIOMetadataController controller

IIOMetadataController, который будет использоваться для предоставления настроек для этого объекта IIOMetadata, когда вызывается метод activateController. Это значение переопределяет любой контроллер по умолчанию, даже если null.

См. также:

Подробное описание конструкторов

IIOMetadata

protected IIOMetadata()

Создаёт пустой объект IIOMetadata. Подкласс отвечает за предоставление значений для всех защищенных переменных-членов, которые позволят любым непереопределенным реализациям по умолчанию методов удовлетворить свои контракты. Например, длина extraMetadataFormatNames не должна быть равна 0.

IIOMetadata

protected IIOMetadata(boolean standardMetadataFormatSupported, String nativeMetadataFormatName, String nativeMetadataFormatClassName, String[] extraMetadataFormatNames, String[] extraMetadataFormatClassNames)

Создаёт объект IIOMetadata с заданными именами форматов и именами классов форматов, а также логическим значением, указывающим, поддерживается ли стандартный формат.

Этот конструктор не пытается проверить имена классов на валидность. Неверные имена классов могут вызвать исключения в последующих вызовах getMetadataFormat.

Параметры:: standardMetadataFormatSupported - true, если этот объект может возвращать или принимать дерево DOM, используя стандартный формат метаданных.; nativeMetadataFormatName - имя нативного формата метаданных, как String, или null, если нативный формат отсутствует.; nativeMetadataFormatClassName - имя класса нативного формата метаданных, или null, если нативный формат отсутствует.; extraMetadataFormatNames - массив имён String, указывающих дополнительные форматы, поддерживаемые этим объектом, или null, если их нет.; extraMetadataFormatClassNames - массив имён классов String, указывающих имена классов любых дополнительных форматов, поддерживаемых этим объектом, или null, если их нет.
Исключения:: IllegalArgumentException - если extraMetadataFormatNames имеет длину 0.; IllegalArgumentException - если extraMetadataFormatNames и extraMetadataFormatClassNames не являются одинаковыми null или не имеют одинаковой длины.

Подробное описание методов

isStandardMetadataFormatSupported

public boolean isStandardMetadataFormatSupported()

Возвращает true, если стандартный формат метаданных поддерживается getMetadataFormat, getAsTree, setFromTree и mergeTree.

Реализация по умолчанию возвращает значение переменной-члена standardFormatSupported.

Возвращает:

true, если стандартный формат метаданных поддерживается.

См. также:

isReadOnly

public abstract boolean isReadOnly()

Возвращает true, если этот объект не поддерживает методы mergeTree, setFromTree и reset.

Возвращает:: true, если объект IIOMetadata не может быть изменён.

getNativeMetadataFormatName

public String getNativeMetadataFormatName()

Возвращает имя "нативного" формата метаданных для этого плагина, который обычно позволяет без потерь кодировать и передавать метаданные, хранящиеся в формате, обрабатываемом этим плагином. Если такой формат не поддерживается, возвращается null.

Структура и содержимое "нативного" формата метаданных определяются плагином, который создал этот объект IIOMetadata. Плагины для простых форматов обычно создают узел-дублер для корня, а затем серию дочерних узлов, представляющих отдельные теги, блоки или пары "ключ/значение". Плагин может выбрать, документировать ли свой нативный формат или нет.

Реализация по умолчанию возвращает значение переменной-члена nativeMetadataFormatName.

Возвращает:

имя нативного формата или null.

См. также:

getExtraMetadataFormatNames

public String[] getExtraMetadataFormatNames()

Возвращает массив строк, содержащих имена дополнительных форматов метаданных, помимо нативного и стандартного, распознаваемых методом getAsTree, setFromTree и mergeTree этого плагина. Если таких дополнительных форматов нет, возвращается null.

Реализация по умолчанию возвращает копию переменной-члена extraMetadataFormatNames.

Возвращает:

массив строк с длиной не меньше 1 или null.

См. также:

getMetadataFormatNames

public String[] getMetadataFormatNames()

Возвращает массив строк, содержащих имена всех форматов метаданных, включая нативный и стандартный, распознаваемых методом getAsTree, setFromTree и mergeTree этого плагина. Если таких форматов нет, возвращается null.

Реализация по умолчанию вызывает getNativeMetadataFormatName, isStandardMetadataFormatSupported и getExtraMetadataFormatNames и возвращает объединённый результат.

Возвращает:

массив строк.

См. также:

getMetadataFormat

public IIOMetadataFormat getMetadataFormat(String formatName)

Возвращает объект IIOMetadataFormat, описывающий заданный формат метаданных, или null, если описание недоступно. Указанное имя должно быть одним из возвращаемых getMetadataFormatNames (т.е., либо именем родного формата, либо именем стандартного формата, либо одним из возвращаемых getExtraMetadataFormatNames).

Реализация по умолчанию проверяет имя на соответствие глобальному стандартному имени формата метаданных и возвращает этот формат, если он поддерживается. В противном случае она проверяет имя на соответствие именам родных форматов, а затем любым дополнительным именам форматов. Если совпадение найдено, она извлекает имя класса IIOMetadataFormat из nativeMetadataFormatClassName или extraMetadataFormatClassNames, как это уместно, и создаёт экземпляр этого класса, используя его метод getInstance.

Parameters:: formatName - желаемый формат метаданных.
Returns:: объект IIOMetadataFormat.
Throws:: IllegalArgumentException - если formatName равен null или не является одним из имён, распознаваемых плагином.; IllegalStateException - если класс, соответствующий имени формата, не может быть загружен.

getAsTree

public abstract Node getAsTree(String formatName)

Возвращает объект XML DOM Node, представляющий корень дерева метаданных, содержащихся в этом объекте в соответствии с соглашениями, определёнными заданным форматом метаданных.

Имена доступных форматов метаданных можно запросить, используя метод getMetadataFormatNames.

Parameters:

formatName - желаемый формат метаданных.

Returns:

объект XML DOM Node, образующий корень дерева.

Throws:

IllegalArgumentException - если formatName равен null или не является одним из имён, возвращаемых getMetadataFormatNames.

See Also:

mergeTree

public abstract void mergeTree(String formatName, Node root) throws IIOInvalidTreeException

Изменяет внутреннее состояние этого объекта IIOMetadata из дерева XML DOM Node, синтаксис которого определён заданным форматом метаданных. Предыдущее состояние изменяется только по мере необходимости для адаптации узлов, присутствующих в данном дереве. Если структура или содержимое дерева некорректны, будет брошено исключение IIOInvalidTreeException.

Поскольку семантика того, как дерево или поддерево может быть слито с другим деревом, полностью зависит от формата, разработчики плагинов могут реализовать этот метод любым образом, наиболее подходящим для формата, включая простое замещение всего существующего состояния содержимым заданного дерева.

Parameters:

formatName - желаемый формат метаданных.

root - объект XML DOM Node, образующий корень дерева.

Throws:

IllegalStateException - если этот объект только для чтения.

IllegalArgumentException - если formatName равен null или не является одним из имён, возвращаемых getMetadataFormatNames.

IllegalArgumentException - если root равен null.

IIOInvalidTreeException - если дерево не может быть успешно проанализировано с использованием правил заданного формата.

See Also:

getStandardChromaNode

protected IIOMetadataNode getStandardChromaNode()

Возвращает IIOMetadataNode, представляющий информацию о цветовом балансе стандартного формата метаданных javax_imageio_1.0, или null, если такая информация недоступна. Этот метод предназначен для вызова вспомогательной процедурой getStandardTree.

Реализация по умолчанию возвращает null.

Подклассы должны переопределять этот метод, чтобы создать соответствующее поддерево, если они хотят поддерживать стандартный формат метаданных.

Returns:

IIOMetadataNode или null.

See Also:

getStandardCompressionNode

protected IIOMetadataNode getStandardCompressionNode()

Возвращает IIOMetadataNode, представляющий информацию о сжатии стандартного формата метаданных javax_imageio_1.0, или null, если такая информация недоступна. Этот метод предназначен для вызова вспомогательной процедурой getStandardTree.

Реализация по умолчанию возвращает null.

Returns:

IIOMetadataNode или null.

See Also:

getStandardDataNode

protected IIOMetadataNode getStandardDataNode()

Возвращает IIOMetadataNode, представляющий информацию о формате данных стандартного формата метаданных javax_imageio_1.0, или null, если такая информация недоступна. Этот метод предназначен для вызова вспомогательной процедурой getStandardTree.

Реализация по умолчанию возвращает null.

Returns:

IIOMetadataNode или null.

See Also:

getStandardDimensionNode

protected IIOMetadataNode getStandardDimensionNode()

Возвращает IIOMetadataNode, представляющий информацию о размерах стандартного формата метаданных javax_imageio_1.0, или null, если такая информация недоступна. Этот метод предназначен для вызова вспомогательной процедурой getStandardTree.

Реализация по умолчанию возвращает null.

Returns:

IIOMetadataNode или null.

See Also:

getStandardDocumentNode

protected IIOMetadataNode getStandardDocumentNode()

Возвращает IIOMetadataNode, представляющий информацию о документе стандартного формата метаданных javax_imageio_1.0, или null, если такая информация недоступна. Этот метод предназначен для вызова вспомогательной процедурой getStandardTree.

Реализация по умолчанию возвращает null.

Returns:

IIOMetadataNode или null.

See Also:

getStandardTextNode

protected IIOMetadataNode getStandardTextNode()

Возвращает IIOMetadataNode, представляющий текстовую информацию стандартного формата метаданных javax_imageio_1.0, или null, если такая информация недоступна. Этот метод предназначен для вызова вспомогательной процедурой getStandardTree.

Реализация по умолчанию возвращает null.

Returns:

IIOMetadataNode или null.

See Also:

getStandardTileNode

protected IIOMetadataNode getStandardTileNode()

Возвращает IIOMetadataNode, представляющий информацию о разбиении на плитки стандартного формата метаданных javax_imageio_1.0, или null, если такая информация недоступна. Этот метод предназначен для вызова вспомогательной процедурой getStandardTree.

Реализация по умолчанию возвращает null.

Returns:

IIOMetadataNode или null.

See Also:

getStandardTransparencyNode

protected IIOMetadataNode getStandardTransparencyNode()

Возвращает IIOMetadataNode, представляющий информацию о прозрачности стандартного формата метаданных javax_imageio_1.0, или null, если такая информация недоступна. Этот метод предназначен для вызова вспомогательной процедурой getStandardTree.

Реализация по умолчанию возвращает null.

Returns:: IIOMetadataNode или null.

getStandardTree

protected final IIOMetadataNode getStandardTree()

Утилитарный метод для возврата дерева IIOMetadataNode, представляющего метаданные, содержащиеся в этом объекте в соответствии с соглашениями стандартного формата метаданных javax_imageio_1.0.

Этот метод вызывает различные методы getStandard*Node, чтобы предоставить каждое из поддеревьев, укоренённых в дочерних узлах корневого узла. Если любой из этих методов возвращает null, соответствующее поддерево будет опущено. Если все они возвращают null, будет возвращено дерево, состоящее из одного корневого узла.

Возвращает:

IIOMetadataNode, представляющее корень дерева метаданных в формате javax_imageio_1.0.

См. также:

setFromTree

public void setFromTree(String formatName, Node root) throws IIOInvalidTreeException

Устанавливает внутреннее состояние этого объекта IIOMetadata из дерева узлов XML DOM Node, синтаксис которого определён заданным форматом метаданных. Предыдущее состояние отбрасывается. Если структура или содержимое дерева некорректны, будет выброшено исключение IIOInvalidTreeException.

Реализация по умолчанию вызывает reset, за которым следует mergeTree(formatName, root).

Параметры:

formatName - желаемый формат метаданных.

root - объект XML DOM Node, образующий корень дерева.

Исключение:

IllegalStateException - если этот объект является только для чтения.

IllegalArgumentException - если formatName имеет значение null или не является одним из имён, возвращаемых методом getMetadataFormatNames.

IllegalArgumentException - если root имеет значение null.

IIOInvalidTreeException - если дерево не может быть успешно проанализировано с помощью правил заданного формата.

См. также:

reset

public abstract void reset()

Сбрасывает все данные, хранящиеся в этом объекте, на значения по умолчанию, обычно на состояние, в котором этот объект находился сразу после создания, хотя точные семантики зависят от плагина. Обратите внимание, что существует множество возможных значений по умолчанию, в зависимости от того, как был создан объект.

Исключение:

IllegalStateException - если этот объект является только для чтения.

См. также:

setController

public void setController(IIOMetadataController controller)

Устанавливает IIOMetadataController, который будет использоваться для предоставления настроек для этого объекта IIOMetadata, когда вызывается метод activateController, перезаписывая любой контроллер по умолчанию. Если аргумент имеет значение null, контроллер не будет использоваться, включая любой по умолчанию. Чтобы восстановить по умолчанию, используйте setController(getDefaultController()).

Реализация по умолчанию устанавливает переменную-член controller в переданное значение.

Параметры:

controller - соответствующий IIOMetadataController или null.

См. также:

getController

public IIOMetadataController getController()

Возвращает установленный в настоящее время IIOMetadataController. Это может быть контроллер по умолчанию, если он есть, null или аргумент последнего вызова метода setController.

Реализация по умолчанию возвращает значение переменной-члена controller.

Возвращает:

текущий установленный IIOMetadataController или null.

См. также:

getDefaultController

public IIOMetadataController getDefaultController()

Возвращает контроллер по умолчанию IIOMetadataController, если он существует, независимо от текущего установленного контроллера. Если контроллер по умолчанию не существует, возвращает null.

Реализация по умолчанию возвращает значение переменной-члена defaultController.

Возвращает:

контроллер по умолчанию IIOMetadataController или null.

См. также:

hasController

public boolean hasController()

Возвращает true, если для этого объекта IIOMetadata установлен контроллер.

Реализация по умолчанию возвращает true, если метод getController возвращает значение, отличное от null.

Возвращает:

true, если контроллер установлен.

См. также:

activateController

public boolean activateController()

Активирует установленный IIOMetadataController для данного объекта IIOMetadata и возвращает полученное значение. Когда этот метод возвращает true, все значения для этого объекта IIOMetadata будут готовы для следующей операции записи. Если возвращается false, никакие настройки в этом объекте не будут изменены (т.е., пользователь отменил операцию).

Обычно контроллер представляет собой графический интерфейс пользователя, предоставляющий интерфейс для подкласса IIOMetadata для конкретного плагина. Однако контроллеры не обязательно должны быть графическими интерфейсами пользователя.

Реализация по умолчанию вызывает getController, а затем вызывает activate на возвращённом объекте, если hasController возвращает true.

Возвращает:

true, если контроллер завершил работу нормально.

Исключение:

IllegalStateException - если контроллер в данный момент не установлен.

См. также:

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://download.java.net/java/early_access/jdk24/docs/api/java.desktop/javax/imageio/metadata/IIOMetadata.html