/* * Copyright (c) 2000, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package javax.imageio.metadata; import org.w3c.dom.Node; import java.lang.reflect.Method; import java.lang.reflect.Module; import java.security.AccessController; import java.security.PrivilegedAction; /** * An abstract class to be extended by objects that represent metadata * (non-image data) associated with images and streams. Plug-ins * represent metadata using opaque, plug-in specific objects. These * objects, however, provide the ability to access their internal * information as a tree of {@code IIOMetadataNode} objects that * support the XML DOM interfaces as well as additional interfaces for * storing non-textual data and retrieving information about legal * data values. The format of such trees is plug-in dependent, but * plug-ins may choose to support a plug-in neutral format described * below. A single plug-in may support multiple metadata formats, * whose names maybe determined by calling * {@code getMetadataFormatNames}. The plug-in may also support * a single special format, referred to as the "native" format, which * is designed to encode its metadata losslessly. This format will * typically be designed specifically to work with a specific file * format, so that images may be loaded and saved in the same format * with no loss of metadata, but may be less useful for transferring * metadata between an {@code ImageReader} and an * {@code ImageWriter} for different image formats. To convert * between two native formats as losslessly as the image file formats * will allow, an {@code ImageTranscoder} object must be used. * * @see javax.imageio.ImageReader#getImageMetadata * @see javax.imageio.ImageReader#getStreamMetadata * @see javax.imageio.ImageReader#readAll * @see javax.imageio.ImageWriter#getDefaultStreamMetadata * @see javax.imageio.ImageWriter#getDefaultImageMetadata * @see javax.imageio.ImageWriter#write * @see javax.imageio.ImageWriter#convertImageMetadata * @see javax.imageio.ImageWriter#convertStreamMetadata * @see javax.imageio.IIOImage * @see javax.imageio.ImageTranscoder * */ public abstract class IIOMetadata { /** * A boolean indicating whether the concrete subclass supports the * standard metadata format, set via the constructor. */ protected boolean standardFormatSupported; /** * The name of the native metadata format for this object, * initialized to {@code null} and set via the constructor. */ protected String nativeMetadataFormatName = null; /** * The name of the class implementing {@code IIOMetadataFormat} * and representing the native metadata format, initialized to * {@code null} and set via the constructor. */ protected String nativeMetadataFormatClassName = null; /** * An array of names of formats, other than the standard and * native formats, that are supported by this plug-in, * initialized to {@code null} and set via the constructor. */ protected String[] extraMetadataFormatNames = null; /** * An array of names of classes implementing {@code IIOMetadataFormat} * and representing the metadata formats, other than the standard and * native formats, that are supported by this plug-in, * initialized to {@code null} and set via the constructor. */ protected String[] extraMetadataFormatClassNames = null; /** * An {@code IIOMetadataController} that is suggested for use * as the controller for this {@code IIOMetadata} object. It * may be retrieved via {@code getDefaultController}. To * install the default controller, call * {@code setController(getDefaultController())}. This * instance variable should be set by subclasses that choose to * provide their own default controller, usually a GUI, for * setting parameters. * * @see IIOMetadataController * @see #getDefaultController */ protected IIOMetadataController defaultController = null; /** * The {@code IIOMetadataController} that will be * used to provide settings for this {@code IIOMetadata} * object when the {@code activateController} method * is called. This value overrides any default controller, * even when {@code null}. * * @see IIOMetadataController * @see #setController(IIOMetadataController) * @see #hasController() * @see #activateController() */ protected IIOMetadataController controller = null; /** * Constructs an empty {@code IIOMetadata} object. The * subclass is responsible for supplying values for all protected * instance variables that will allow any non-overridden default * implementations of methods to satisfy their contracts. For example, * {@code extraMetadataFormatNames} should not have length 0. */ protected IIOMetadata() {} /** * Constructs an {@code IIOMetadata} object with the given * format names and format class names, as well as a boolean * indicating whether the standard format is supported. * *
This constructor does not attempt to check the class names * for validity. Invalid class names may cause exceptions in * subsequent calls to {@code getMetadataFormat}. * * @param standardMetadataFormatSupported {@code true} if * this object can return or accept a DOM tree using the standard * metadata format. * @param nativeMetadataFormatName the name of the native metadata * format, as a {@code String}, or {@code null} if there * is no native format. * @param nativeMetadataFormatClassName the name of the class of * the native metadata format, or {@code null} if there is * no native format. * @param extraMetadataFormatNames an array of {@code String}s * indicating additional formats supported by this object, or * {@code null} if there are none. * @param extraMetadataFormatClassNames an array of {@code String}s * indicating the class names of any additional formats supported by * this object, or {@code null} if there are none. * * @exception IllegalArgumentException if * {@code extraMetadataFormatNames} has length 0. * @exception IllegalArgumentException if * {@code extraMetadataFormatNames} and * {@code extraMetadataFormatClassNames} are neither both * {@code null}, nor of the same length. */ protected IIOMetadata(boolean standardMetadataFormatSupported, String nativeMetadataFormatName, String nativeMetadataFormatClassName, String[] extraMetadataFormatNames, String[] extraMetadataFormatClassNames) { this.standardFormatSupported = standardMetadataFormatSupported; this.nativeMetadataFormatName = nativeMetadataFormatName; this.nativeMetadataFormatClassName = nativeMetadataFormatClassName; if (extraMetadataFormatNames != null) { if (extraMetadataFormatNames.length == 0) { throw new IllegalArgumentException ("extraMetadataFormatNames.length == 0!"); } if (extraMetadataFormatClassNames == null) { throw new IllegalArgumentException ("extraMetadataFormatNames != null && extraMetadataFormatClassNames == null!"); } if (extraMetadataFormatClassNames.length != extraMetadataFormatNames.length) { throw new IllegalArgumentException ("extraMetadataFormatClassNames.length != extraMetadataFormatNames.length!"); } this.extraMetadataFormatNames = extraMetadataFormatNames.clone(); this.extraMetadataFormatClassNames = extraMetadataFormatClassNames.clone(); } else { if (extraMetadataFormatClassNames != null) { throw new IllegalArgumentException ("extraMetadataFormatNames == null && extraMetadataFormatClassNames != null!"); } } } /** * Returns {@code true} if the standard metadata format is * supported by {@code getMetadataFormat}, * {@code getAsTree}, {@code setFromTree}, and * {@code mergeTree}. * *
The default implementation returns the value of the * {@code standardFormatSupported} instance variable. * * @return {@code true} if the standard metadata format * is supported. * * @see #getAsTree * @see #setFromTree * @see #mergeTree * @see #getMetadataFormat */ public boolean isStandardMetadataFormatSupported() { return standardFormatSupported; } /** * Returns {@code true} if this object does not support the * {@code mergeTree}, {@code setFromTree}, and * {@code reset} methods. * * @return true if this {@code IIOMetadata} object cannot be * modified. */ public abstract boolean isReadOnly(); /** * 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. If no such format is supported, * {@code null} will be returned. * *
The structure and contents of the "native" metadata format * are defined by the plug-in that created this * {@code IIOMetadata} object. Plug-ins for simple formats * will usually create a dummy node for the root, and then a * series of child nodes representing individual tags, chunks, or * keyword/value pairs. A plug-in may choose whether or not to * document its native format. * *
The default implementation returns the value of the * {@code nativeMetadataFormatName} instance variable. * * @return the name of the native format, or {@code null}. * * @see #getExtraMetadataFormatNames * @see #getMetadataFormatNames */ public String getNativeMetadataFormatName() { return nativeMetadataFormatName; } /** * Returns an array of {@code String}s containing the names * of additional metadata formats, other than the native and standard * formats, recognized by this plug-in's * {@code getAsTree}, {@code setFromTree}, and * {@code mergeTree} methods. If there are no such additional * formats, {@code null} is returned. * *
The default implementation returns a clone of the * {@code extraMetadataFormatNames} instance variable. * * @return an array of {@code String}s with length at least * 1, or {@code null}. * * @see #getAsTree * @see #setFromTree * @see #mergeTree * @see #getNativeMetadataFormatName * @see #getMetadataFormatNames */ public String[] getExtraMetadataFormatNames() { if (extraMetadataFormatNames == null) { return null; } return extraMetadataFormatNames.clone(); } /** * Returns an array of {@code String}s containing the names * of all metadata formats, including the native and standard * formats, recognized by this plug-in's {@code getAsTree}, * {@code setFromTree}, and {@code mergeTree} methods. * If there are no such formats, {@code null} is returned. * *
The default implementation calls * {@code getNativeMetadataFormatName}, * {@code isStandardMetadataFormatSupported}, and * {@code getExtraMetadataFormatNames} and returns the * combined results. * * @return an array of {@code String}s. * * @see #getNativeMetadataFormatName * @see #isStandardMetadataFormatSupported * @see #getExtraMetadataFormatNames */ public String[] getMetadataFormatNames() { String nativeName = getNativeMetadataFormatName(); String standardName = isStandardMetadataFormatSupported() ? IIOMetadataFormatImpl.standardMetadataFormatName : null; String[] extraNames = getExtraMetadataFormatNames(); int numFormats = 0; if (nativeName != null) { ++numFormats; } if (standardName != null) { ++numFormats; } if (extraNames != null) { numFormats += extraNames.length; } if (numFormats == 0) { return null; } String[] formats = new String[numFormats]; int index = 0; if (nativeName != null) { formats[index++] = nativeName; } if (standardName != null) { formats[index++] = standardName; } if (extraNames != null) { for (int i = 0; i < extraNames.length; i++) { formats[index++] = extraNames[i]; } } return formats; } /** * Returns an {@code IIOMetadataFormat} object describing the * given metadata format, or {@code null} if no description * is available. The supplied name must be one of those returned * by {@code getMetadataFormatNames} (i.e., either the * native format name, the standard format name, or one of those * returned by {@code getExtraMetadataFormatNames}). * *
The default implementation checks the name against the
* global standard metadata format name, and returns that format
* if it is supported. Otherwise, it checks against the native
* format names followed by any additional format names. If a
* match is found, it retrieves the name of the
* {@code IIOMetadataFormat} class from
* {@code nativeMetadataFormatClassName} or
* {@code extraMetadataFormatClassNames} as appropriate, and
* constructs an instance of that class using its
* {@code getInstance} method.
*
* @param formatName the desired metadata format.
*
* @return an {@code IIOMetadataFormat} object.
*
* @exception IllegalArgumentException if {@code formatName}
* is {@code null} or is not one of the names recognized by
* the plug-in.
* @exception IllegalStateException if the class corresponding to
* the format name cannot be loaded.
*/
public IIOMetadataFormat getMetadataFormat(String formatName) {
if (formatName == null) {
throw new IllegalArgumentException("formatName == null!");
}
if (standardFormatSupported
&& formatName.equals
(IIOMetadataFormatImpl.standardMetadataFormatName)) {
return IIOMetadataFormatImpl.getStandardFormatInstance();
}
String formatClassName = null;
if (formatName.equals(nativeMetadataFormatName)) {
formatClassName = nativeMetadataFormatClassName;
} else if (extraMetadataFormatNames != null) {
for (int i = 0; i < extraMetadataFormatNames.length; i++) {
if (formatName.equals(extraMetadataFormatNames[i])) {
formatClassName = extraMetadataFormatClassNames[i];
break; // out of for
}
}
}
if (formatClassName == null) {
throw new IllegalArgumentException("Unsupported format name");
}
try {
final String className = formatClassName;
// Try to load from the module of the IIOMetadata implementation
// for this plugin since the IIOMetadataImpl is part of the plugin
PrivilegedAction The names of the available metadata formats may be queried
* using the {@code getMetadataFormatNames} method.
*
* @param formatName the desired metadata format.
*
* @return an XML DOM {@code Node} object forming the
* root of a tree.
*
* @exception IllegalArgumentException if {@code formatName}
* is {@code null} or is not one of the names returned by
* {@code getMetadataFormatNames}.
*
* @see #getMetadataFormatNames
* @see #setFromTree
* @see #mergeTree
*/
public abstract Node getAsTree(String formatName);
/**
* Alters the internal state of this {@code IIOMetadata}
* object from a tree of XML DOM {@code Node}s whose syntax
* is defined by the given metadata format. The previous state is
* altered only as necessary to accommodate the nodes that are
* present in the given tree. If the tree structure or contents
* are invalid, an {@code IIOInvalidTreeException} will be
* thrown.
*
* As the semantics of how a tree or subtree may be merged with
* another tree are completely format-specific, plug-in authors may
* implement this method in whatever manner is most appropriate for
* the format, including simply replacing all existing state with the
* contents of the given tree.
*
* @param formatName the desired metadata format.
* @param root an XML DOM {@code Node} object forming the
* root of a tree.
*
* @exception IllegalStateException if this object is read-only.
* @exception IllegalArgumentException if {@code formatName}
* is {@code null} or is not one of the names returned by
* {@code getMetadataFormatNames}.
* @exception IllegalArgumentException if {@code root} is
* {@code null}.
* @exception IIOInvalidTreeException if the tree cannot be parsed
* successfully using the rules of the given format.
*
* @see #getMetadataFormatNames
* @see #getAsTree
* @see #setFromTree
*/
public abstract void mergeTree(String formatName, Node root)
throws IIOInvalidTreeException;
/**
* Returns an {@code IIOMetadataNode} representing the chroma
* information of the standard {@code javax_imageio_1.0}
* metadata format, or {@code null} if no such information is
* available. This method is intended to be called by the utility
* routine {@code getStandardTree}.
*
* The default implementation returns {@code null}.
*
* Subclasses should override this method to produce an
* appropriate subtree if they wish to support the standard
* metadata format.
*
* @return an {@code IIOMetadataNode}, or {@code null}.
*
* @see #getStandardTree
*/
protected IIOMetadataNode getStandardChromaNode() {
return null;
}
/**
* Returns an {@code IIOMetadataNode} representing the
* compression information of the standard
* {@code javax_imageio_1.0} metadata format, or
* {@code null} if no such information is available. This
* method is intended to be called by the utility routine
* {@code getStandardTree}.
*
* The default implementation returns {@code null}.
*
* Subclasses should override this method to produce an
* appropriate subtree if they wish to support the standard
* metadata format.
*
* @return an {@code IIOMetadataNode}, or {@code null}.
*
* @see #getStandardTree
*/
protected IIOMetadataNode getStandardCompressionNode() {
return null;
}
/**
* Returns an {@code IIOMetadataNode} representing the data
* format information of the standard
* {@code javax_imageio_1.0} metadata format, or
* {@code null} if no such information is available. This
* method is intended to be called by the utility routine
* {@code getStandardTree}.
*
* The default implementation returns {@code null}.
*
* Subclasses should override this method to produce an
* appropriate subtree if they wish to support the standard
* metadata format.
*
* @return an {@code IIOMetadataNode}, or {@code null}.
*
* @see #getStandardTree
*/
protected IIOMetadataNode getStandardDataNode() {
return null;
}
/**
* Returns an {@code IIOMetadataNode} representing the
* dimension information of the standard
* {@code javax_imageio_1.0} metadata format, or
* {@code null} if no such information is available. This
* method is intended to be called by the utility routine
* {@code getStandardTree}.
*
* The default implementation returns {@code null}.
*
* Subclasses should override this method to produce an
* appropriate subtree if they wish to support the standard
* metadata format.
*
* @return an {@code IIOMetadataNode}, or {@code null}.
*
* @see #getStandardTree
*/
protected IIOMetadataNode getStandardDimensionNode() {
return null;
}
/**
* Returns an {@code IIOMetadataNode} representing the document
* information of the standard {@code javax_imageio_1.0}
* metadata format, or {@code null} if no such information is
* available. This method is intended to be called by the utility
* routine {@code getStandardTree}.
*
* The default implementation returns {@code null}.
*
* Subclasses should override this method to produce an
* appropriate subtree if they wish to support the standard
* metadata format.
*
* @return an {@code IIOMetadataNode}, or {@code null}.
*
* @see #getStandardTree
*/
protected IIOMetadataNode getStandardDocumentNode() {
return null;
}
/**
* Returns an {@code IIOMetadataNode} representing the textual
* information of the standard {@code javax_imageio_1.0}
* metadata format, or {@code null} if no such information is
* available. This method is intended to be called by the utility
* routine {@code getStandardTree}.
*
* The default implementation returns {@code null}.
*
* Subclasses should override this method to produce an
* appropriate subtree if they wish to support the standard
* metadata format.
*
* @return an {@code IIOMetadataNode}, or {@code null}.
*
* @see #getStandardTree
*/
protected IIOMetadataNode getStandardTextNode() {
return null;
}
/**
* Returns an {@code IIOMetadataNode} representing the tiling
* information of the standard {@code javax_imageio_1.0}
* metadata format, or {@code null} if no such information is
* available. This method is intended to be called by the utility
* routine {@code getStandardTree}.
*
* The default implementation returns {@code null}.
*
* Subclasses should override this method to produce an
* appropriate subtree if they wish to support the standard
* metadata format.
*
* @return an {@code IIOMetadataNode}, or {@code null}.
*
* @see #getStandardTree
*/
protected IIOMetadataNode getStandardTileNode() {
return null;
}
/**
* Returns an {@code IIOMetadataNode} representing the
* transparency information of the standard
* {@code javax_imageio_1.0} metadata format, or
* {@code null} if no such information is available. This
* method is intended to be called by the utility routine
* {@code getStandardTree}.
*
* The default implementation returns {@code null}.
*
* Subclasses should override this method to produce an
* appropriate subtree if they wish to support the standard
* metadata format.
*
* @return an {@code IIOMetadataNode}, or {@code null}.
*/
protected IIOMetadataNode getStandardTransparencyNode() {
return null;
}
/**
* Appends a new node to an existing node, if the new node is
* non-{@code null}.
*/
private void append(IIOMetadataNode root, IIOMetadataNode node) {
if (node != null) {
root.appendChild(node);
}
}
/**
* A utility method to return a tree of
* {@code IIOMetadataNode}s representing the metadata
* contained within this object according to the conventions of
* the standard {@code javax_imageio_1.0} metadata format.
*
* This method calls the various {@code getStandard*Node}
* methods to supply each of the subtrees rooted at the children
* of the root node. If any of those methods returns
* {@code null}, the corresponding subtree will be omitted.
* If all of them return {@code null}, a tree consisting of a
* single root node will be returned.
*
* @return an {@code IIOMetadataNode} representing the root
* of a metadata tree in the {@code javax_imageio_1.0}
* format.
*
* @see #getStandardChromaNode
* @see #getStandardCompressionNode
* @see #getStandardDataNode
* @see #getStandardDimensionNode
* @see #getStandardDocumentNode
* @see #getStandardTextNode
* @see #getStandardTileNode
* @see #getStandardTransparencyNode
*/
protected final IIOMetadataNode getStandardTree() {
IIOMetadataNode root = new IIOMetadataNode
(IIOMetadataFormatImpl.standardMetadataFormatName);
append(root, getStandardChromaNode());
append(root, getStandardCompressionNode());
append(root, getStandardDataNode());
append(root, getStandardDimensionNode());
append(root, getStandardDocumentNode());
append(root, getStandardTextNode());
append(root, getStandardTileNode());
append(root, getStandardTransparencyNode());
return root;
}
/**
* Sets the internal state of this {@code IIOMetadata} object
* from a tree of XML DOM {@code Node}s whose syntax is
* defined by the given metadata format. The previous state is
* discarded. If the tree's structure or contents are invalid, an
* {@code IIOInvalidTreeException} will be thrown.
*
* The default implementation calls {@code reset}
* followed by {@code mergeTree(formatName, root)}.
*
* @param formatName the desired metadata format.
* @param root an XML DOM {@code Node} object forming the
* root of a tree.
*
* @exception IllegalStateException if this object is read-only.
* @exception IllegalArgumentException if {@code formatName}
* is {@code null} or is not one of the names returned by
* {@code getMetadataFormatNames}.
* @exception IllegalArgumentException if {@code root} is
* {@code null}.
* @exception IIOInvalidTreeException if the tree cannot be parsed
* successfully using the rules of the given format.
*
* @see #getMetadataFormatNames
* @see #getAsTree
* @see #mergeTree
*/
public void setFromTree(String formatName, Node root)
throws IIOInvalidTreeException {
reset();
mergeTree(formatName, root);
}
/**
* 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.
* Note that there are many possible default values, depending on
* how the object was created.
*
* @exception IllegalStateException if this object is read-only.
*
* @see javax.imageio.ImageReader#getStreamMetadata
* @see javax.imageio.ImageReader#getImageMetadata
* @see javax.imageio.ImageWriter#getDefaultStreamMetadata
* @see javax.imageio.ImageWriter#getDefaultImageMetadata
*/
public abstract void reset();
/**
* Sets the {@code IIOMetadataController} to be used
* to provide settings for this {@code IIOMetadata}
* object when the {@code activateController} method
* is called, overriding any default controller. If the
* argument is {@code null}, no controller will be
* used, including any default. To restore the default, use
* {@code setController(getDefaultController())}.
*
* The default implementation sets the {@code controller}
* instance variable to the supplied value.
*
* @param controller An appropriate
* {@code IIOMetadataController}, or {@code null}.
*
* @see IIOMetadataController
* @see #getController
* @see #getDefaultController
* @see #hasController
* @see #activateController()
*/
public void setController(IIOMetadataController controller) {
this.controller = controller;
}
/**
* Returns whatever {@code IIOMetadataController} is currently
* installed. This could be the default if there is one,
* {@code null}, or the argument of the most recent call
* to {@code setController}.
*
* The default implementation returns the value of the
* {@code controller} instance variable.
*
* @return the currently installed
* {@code IIOMetadataController}, or {@code null}.
*
* @see IIOMetadataController
* @see #setController
* @see #getDefaultController
* @see #hasController
* @see #activateController()
*/
public IIOMetadataController getController() {
return controller;
}
/**
* Returns the default {@code IIOMetadataController}, if there
* is one, regardless of the currently installed controller. If
* there is no default controller, returns {@code null}.
*
* The default implementation returns the value of the
* {@code defaultController} instance variable.
*
* @return the default {@code IIOMetadataController}, or
* {@code null}.
*
* @see IIOMetadataController
* @see #setController(IIOMetadataController)
* @see #getController
* @see #hasController
* @see #activateController()
*/
public IIOMetadataController getDefaultController() {
return defaultController;
}
/**
* Returns {@code true} if there is a controller installed
* for this {@code IIOMetadata} object.
*
* The default implementation returns {@code true} if the
* {@code getController} method returns a
* non-{@code null} value.
*
* @return {@code true} if a controller is installed.
*
* @see IIOMetadataController
* @see #setController(IIOMetadataController)
* @see #getController
* @see #getDefaultController
* @see #activateController()
*/
public boolean hasController() {
return (getController() != null);
}
/**
* Activates the installed {@code IIOMetadataController} for
* this {@code IIOMetadata} object and returns the resulting
* value. When this method returns {@code true}, all values for this
* {@code IIOMetadata} object will be ready for the next write
* operation. If {@code false} is
* returned, no settings in this object will have been disturbed
* (i.e., the user canceled the operation).
*
* Ordinarily, the controller will be a GUI providing a user
* interface for a subclass of {@code IIOMetadata} for a
* particular plug-in. Controllers need not be GUIs, however.
*
* The default implementation calls {@code getController}
* and the calls {@code activate} on the returned object if
* {@code hasController} returns {@code true}.
*
* @return {@code true} if the controller completed normally.
*
* @exception IllegalStateException if there is no controller
* currently installed.
*
* @see IIOMetadataController
* @see #setController(IIOMetadataController)
* @see #getController
* @see #getDefaultController
* @see #hasController
*/
public boolean activateController() {
if (!hasController()) {
throw new IllegalStateException("hasController() == false!");
}
return getController().activate(this);
}
}