com.sun.rave.designtime
Interface DesignContext

All Superinterfaces:

DisplayItem

All Known Subinterfaces:

FacesDesignContext, MarkupDesignContext

public interface DesignContext

extends DisplayItem

A DesignContext is a 'host' for DesignBean instances at design-time. The DesignContext represents the 'backing file' or 'persistence model' for a design-time session. A DesignContext is the container (instance host) for a set of DesignBeans. For example, in a JSF application, the DesignContext represents the logical backing file which is the combination of the 'Page1.jsp' and the 'Page1.java' files.

IMPLEMENTED BY CREATOR - This interface is implemented by Creator for use by the component (bean) author.

Version:

1.0

Author:

Joe Nuxoll

Method Summary

void	addDesignContextListener(DesignContextListener listener) Adds a listener to this DesignContext
java.lang.String	addResource(java.net.URL resource, boolean copy) Adds a resource reference to this DesignContext, and converts the external URL into a local resource identifyer String.
boolean	canCreateBean(java.lang.String classname, DesignBean parent, Position position) Returns true if the specified type (classname) of JavaBean can be created as a child of the specified parent DesignBean at the specified position.
boolean	canMoveBean(DesignBean designBean, DesignBean newParent, Position position) Returns true if the specified DesignBean can be can be moved to be a child of the specified parent DesignBean at the specified position.
java.awt.datatransfer.Transferable	copyBeans(DesignBean[] beans) Copies a set of DesignBean instances into a clipboard-like format.
DesignBean	createBean(java.lang.String classname, DesignBean parent, Position position) Creates an instance of a JavaBean of the specified type (classname), as a child of the specified parent DesignBean at the specified position.
boolean	deleteBean(DesignBean designBean) Deletes a DesignBean object (and removes all persistence).
DesignBean	getBeanByName(java.lang.String instanceName) Returns a DesignBean (design-time proxy) to represent the JavaBean with the specified instance name.
DesignBean	getBeanForInstance(java.lang.Object beanInstance) Returns a DesignBean (design-time proxy) to represent the specified JavaBean instance.
DesignBean[]	getBeans() Returns an array of all the DesignBeans within the scope of this DesignContext.
DesignBean[]	getBeansOfType(java.lang.Class beanClass) Returns a DesignBean array (design-time proxies) representing the JavaBeans within the scope of this DesignContext that are assignable from the specified class type.
java.lang.Object	getContextData(java.lang.String key) Retrieves the value for a name-value pair of data on this DesignContext.
DesignContextListener[]	getDesignContextListeners() Returns the array of current listeners to this DesignContext
IdeProject	getProject() Returns the project, which is the top-level container for all contexts.
DesignBean	getRootContainer() Returns the root container DesignBean for this DesignContext.
boolean	moveBean(DesignBean designBean, DesignBean newParent, Position position) Moves a DesignBean, to become a child of the specified parent DesignBean at the specified position.
DesignBean[]	pasteBeans(java.awt.datatransfer.Transferable persistData, DesignBean newParent, Position position) Pastes a set of DesignBean instances (acquired via copyBeans) into the specified parent DesignBean at the specified position.
void	removeDesignContextListener(DesignContextListener listener) Removes a listener from this DesignContext
java.net.URL	resolveResource(java.lang.String localResource) Resolves a local resource identifyer String into a fully-qualified URL.
void	setContextData(java.lang.String key, java.lang.Object data) Sets a name-value pair of data on this DesignContext.

Methods inherited from interface com.sun.rave.designtime.DisplayItem

getDescription, getDisplayName, getHelpKey, getLargeIcon, getSmallIcon

Method Detail

addDesignContextListener

public void addDesignContextListener(DesignContextListener listener)

Adds a listener to this DesignContext

Parameters:

listener - The desired listener to add

addResource

public java.lang.String addResource(java.net.URL resource,
                                    boolean copy)
                             throws java.io.IOException

Adds a resource reference to this DesignContext, and converts the external URL into a local resource identifyer String. This may also copy (if specified) an external resource into the project.

Parameters:

resource - A URL pointing to the desired external resource

copy - true if the resource should be copied into the project, false if not

Returns:

The resulting relative resource identifyer String. This will be a local relative resource if the external resource was copied into the project.

Throws:

java.io.IOException

canCreateBean

public boolean canCreateBean(java.lang.String classname,
                             DesignBean parent,
                             Position position)

Returns true if the specified type (classname) of JavaBean can be created as a child of the specified parent DesignBean at the specified position. This is a test call that should be performed before calling the createBean method.

Parameters:

classname - The fully qualified class name of the JavaBean to be created

parent - The DesignBean parent for the JavaBean to be created

position - The desired position for the JavaBean to be created

Returns:

true if a matching call to 'createBean' would succeed, or false if not

See Also:

createBean(String, DesignBean, Position)

canMoveBean

public boolean canMoveBean(DesignBean designBean,
                           DesignBean newParent,
                           Position position)

Returns true if the specified DesignBean can be can be moved to be a child of the specified parent DesignBean at the specified position. This is a test call that should be performed before calling the moveBean method.

Parameters:

designBean - The DesignBean to be moved

newParent - The new DesignBean parent for the DesignBean

position - The desired position for the DesignBean to be moved

Returns:

true if a matching call to 'moveBean' would succeed, or false if not

See Also:

moveBean(DesignBean, DesignBean, Position)

copyBeans

public java.awt.datatransfer.Transferable copyBeans(DesignBean[] beans)

Copies a set of DesignBean instances into a clipboard-like format. This returns a Transferable object that stores all the necessary data for the pasteBeans method.

Returns:

the resulting Transferable object representing the copied beans

See Also:

pasteBeans(java.awt.datatransfer.Transferable, DesignBean, Position)

createBean

public DesignBean createBean(java.lang.String classname,
                             DesignBean parent,
                             Position position)

Creates an instance of a JavaBean of the specified type (classname), as a child of the specified parent DesignBean at the specified position. If successful, a DesignBean representing the newly created bean is returned. Before this method is called, a test call should be performed to the canCreateBean method.

Parameters:

classname - The fully qualified class name of the JavaBean to be created

parent - The DesignBean parent for the JavaBean to be created

position - The desired position for the JavaBean to be created

Returns:

A DesignBean representing the JavaBean that was created, or null if the operation failed

See Also:

canCreateBean(String, DesignBean, Position)

deleteBean

public boolean deleteBean(DesignBean designBean)

Deletes a DesignBean object (and removes all persistence). Returns true if the delete was successful, false if not.

Parameters:

designBean - The desired DesignBean to delete

Returns:

true if the delete operation was successful, false if not

getBeanByName

public DesignBean getBeanByName(java.lang.String instanceName)

Returns a DesignBean (design-time proxy) to represent the JavaBean with the specified instance name. This must be an instance that lives within the scope of this DesignContext, or the method will return null.

Parameters:

instanceName - The String instance name of the desired JavaBean

Returns:

A DesignBean (design-time proxy) representing the specified bean, or null if the specified instance name does not represent a JavaBean within the scope of this DesignContext

getBeanForInstance

public DesignBean getBeanForInstance(java.lang.Object beanInstance)

Returns a DesignBean (design-time proxy) to represent the specified JavaBean instance. This must be an instance that lives within the scope of this DesignContext, or the method will return null.

Parameters:

beanInstance - A live instance of a JavaBean

Returns:

A DesignBean (design-time proxy) representing the specified bean instance, or null if the specified Object does not represent a JavaBean within the scope of this DesignContext

getBeans

public DesignBean[] getBeans()

Returns an array of all the DesignBeans within the scope of this DesignContext. This is a flat list of instances, ignoring the containership hierarchy. To navigate the containership hierarchy, use the getRootContainer() method.

Returns:

An array of DesignBean representing the JavaBeans within the scope of this DesignContext

See Also:

getRootContainer()

getBeansOfType

public DesignBean[] getBeansOfType(java.lang.Class beanClass)

Returns a DesignBean array (design-time proxies) representing the JavaBeans within the scope of this DesignContext that are assignable from the specified class type. This uses Class.isAssignableFrom(...) to determine if a JavaBean satisfies the specified criteria, so subtypes of the specified type will be included.

Parameters:

beanClass - The desired class type

Returns:

An array of DesignBean representing the JavaBeans within the scope of this DesignContext that are assignable from the specified class type

See Also:

Class.isAssignableFrom(Class)

getContextData

public java.lang.Object getContextData(java.lang.String key)

Retrieves the value for a name-value pair of data on this DesignContext. This name-value pair is stored in the associated project file (as text) that contains this DesignContext, so this data is retrievable in any IDE session once it has been set.

NOTE: The 'data' Object can be a simple String or a complex (non-String) Object. Either way, it will be stored as text in the project file and will be associated with this DesignContext. When the project file is written to disk, any complex (non-String) objects will be converted to String using the 'toString()' method. If a component author wishes to store a complex (non-String) object, they must be sure to override the 'toString()' method on their object to serialize out enough information to be able to restore the object when a subsequent call to 'getContextData' returns a String. Though a complex object was stored via the 'setContextData' method, a component author *may* get back a String from 'getContextData' if the project has been saved and reopened since the previous call to 'setContextData'. It is the responsibility of the component author to reconstruct the complex object from the String, and if desired, put it back into the context using the 'setContextData' method passing the newly constructed object in. This way, all subsequent calls to 'getContextData' with that key will return the complex object instance - until the project is closed and restored.

Parameters:

key - The desired String key to retrieve the data object for

Returns:

The data object that is currently stored under this key - this may be a String or an Object, based on what was stored using 'setContextData'. NOTE: This will always be a String after the project file is read from disk, even if the stored object was not a String - it will have been converted using the 'toString()' method.

See Also:

setContextData(String, Object)

getDesignContextListeners

public DesignContextListener[] getDesignContextListeners()

Returns the array of current listeners to this DesignContext

Returns:

An array of listeners currently listening to this DesignContext

getProject

public IdeProject getProject()

Returns the project, which is the top-level container for all contexts.

Returns:

The IdeProject associated with this DesignContext

getRootContainer

public DesignBean getRootContainer()

Returns the root container DesignBean for this DesignContext. This is typically the "this" component being designed. For example, this would be the view root in a JSF application. The children of the root container are the items you see on the page. To get all of the DesignBeans within the scope of this context (ignoring the containership hierarchy), use the getBeans() method.

Returns:

The root container DesignBean for this DesignContext

See Also:

getBeans()

moveBean

public boolean moveBean(DesignBean designBean,
                        DesignBean newParent,
                        Position position)

Moves a DesignBean, to become a child of the specified parent DesignBean at the specified position. Returns true if successful, false if not. Before this method is called, a test call should be performed to the canMoveBean method.

Parameters:

designBean - The DesignBean to move

newParent - The new DesignBean parent for the DesignBean

position - The desired position for the DesignBean to be moved

Returns:

true if move was succeessful, or false if not

See Also:

canMoveBean(DesignBean, DesignBean, Position)

pasteBeans

public DesignBean[] pasteBeans(java.awt.datatransfer.Transferable persistData,
                               DesignBean newParent,
                               Position position)

Pastes a set of DesignBean instances (acquired via copyBeans) into the specified parent DesignBean at the specified position. This returns an array of DesignBean(s), representing the newly pasted children.

Parameters:

persistData - The Transferable object acquired via 'copyBeans' that contains the data representing the DesignBean(s) to be pasted

newParent - The desired new parent DesignBean to paste the DesignBean(s) into

position - The desired new position for the pasted DesignBean(s)

Returns:

The newly created DesignBean instances

See Also:

copyBeans(DesignBean[])

removeDesignContextListener

public void removeDesignContextListener(DesignContextListener listener)

Removes a listener from this DesignContext

Parameters:

listener - The desired listener to remove

resolveResource

public java.net.URL resolveResource(java.lang.String localResource)

Resolves a local resource identifyer String into a fully-qualified URL.

Parameters:

localResource - A local resource identifier string

Returns:

A fully-qualified URL

setContextData

public void setContextData(java.lang.String key,
                           java.lang.Object data)

Sets a name-value pair of data on this DesignContext. This name-value pair will be stored in the associated project file (as text) that contains this DesignContext, so this data is retrievable in a future IDE session.

NOTE: The 'data' Object can be a simple String or a complex (non-String) Object. Either way, it will be stored as text in the project file and will be associated with this DesignContext. When the project file is written to disk, any complex (non-String) objects will be converted to String using the 'toString()' method. If a component author wishes to store a complex (non-String) object, they must be sure to override the 'toString()' method on their object to serialize out enough information to be able to restore the object when a subsequent call to 'getContextData' returns a String. Though a complex object was stored via the 'setContextData' method, a component author *may* get back a String from 'getContextData' if the project has been saved and reopened since the previous call to 'setContextData'. It is the responsibility of the component author to reconstruct the complex object from the String, and if desired, put it back into the context using the 'setContextData' method passing the newly constructed object in. This way, all subsequent calls to 'getContextData' with that key will return the complex object instance - until the project is closed and restored.

Parameters:

key - The String key to store the data object under

data - The data object to store - this may be a String or any complex object, but it will be stored as a string using the 'toString()' method when the project file is written to disk.

See Also:

getContextData(String)