com.im.df.api.support
Interface DFNewType<E extends DFItem>

public interface DFNewType<E extends DFItem>

NewType is the object with the ability to create new items. It is always related to the context where it was obtained from. If you get it from some specific fields container instance it will create new fields in this context (all newly created fields will belong to the same parent entity).

NewType is supposed to be used by user code (usually UI code) like wizards, menu actions; or by some macro style scripts which can create bunch of new items (e.g. new entity, some of its fields, empty datatree with only this entity as a root and some plain view).

Each new type can provide options (parameters for object creation). DFNewType always returns the same instance. So you just need to take it (getOptions()) and set up it. If you call create method, options must be in valid state otherwise create method fails.

NewType is prepared to be used by user interface code as well as by these code scripts. So there are basically two scenarios how to use newtype.

User interface code:

• Obtain list of all new types from parent container
• Allow user to select the best newtype (for the appropriate item type) using getName(). UI wizard can also offer some type of filtering based on isForAddingExistingItem() method return value
• Get the options object from the selected newtype and try to find UI customizer for it (see com.im.df.util.DFUtils.findUICustomizer(Object,boolean). TODO API - this class is currently in DIF Impl, but will be moved to API
• Show customizer and allow user to edit creation parameters (e.g. name of new item)
• Call create(DFEnvironmentRW) method

The second approach (non-UI code) can use little modified scenario:

• Obtain list of all new types from parent container
• Find the appropriate new type using the list of capabilities. For example if you want to create new field and you know that you want to use if for numbers, you can filter only newtypes which declare that newly created item will have DFFieldIntegerCapability. You can also filter out the newtypes which have some unwanted capabilities (e.g. DFFieldChemicalTermsCapability). If you are still not sure it is possible to use getType() method to find the exact implementation you need.
• Take the selected newtype and get options for it.
• Use introspection to find getters and setters methods. It's supposed that options is Java Bean and so you can set creating arguments this way. The alternative way is usage of some of inner interface of DFNewTypeWellKnownOptions. For example if you are creating a new database field, you can try to cast Options object to DFNewTypeWellKnownOptions.NewDBField and set arguments using its methods.
• Call create(DFEnvironmentRW) method

Method Summary

Collection<E>	create(DFEnvironmentRW env) Create one or more new DFItems is one step.
List<Class>	getCapabilityTypes() Get the list of capabilities of the future DFItem(s) created by this newtype.
String	getName() Human readable name of this new type.
DFNewTypeOptions	getOptions()
String	getType() Get the code-name (implementation unique name) of this newtype.
boolean	isForAddingExistingItem() Is this new type used for creating new DFItem metaobject for some object on the physical level which already exists? DFItems are usually metadata objects for some underlayed artefacts, but this is not necessary.
boolean	isForCreatingSingleItem() Test the type of newtype.

Method Detail

getName

String getName()

Human readable name of this new type. The name should describe the element which will be created using this new type.

getCapabilityTypes

List<Class> getCapabilityTypes()

Get the list of capabilities of the future DFItem(s) created by this newtype.

getType

String getType()

Get the code-name (implementation unique name) of this newtype. It should be the same like the type which returns DFItem.getType() method.

isForAddingExistingItem

boolean isForAddingExistingItem()

Is this new type used for creating new DFItem metaobject for some object on the physical level which already exists? DFItems are usually metadata objects for some underlayed artefacts, but this is not necessary. It always depends on the specific implementations and on the type of DFItem. For example DFEntity can represents database table as well as file. But there can also be only memory implementation, which does not have anything under it.

Some DFItems are really virtual and have no artefacts - typically DFDataTrees and DFViews.

If there is no underlayed artefacts (database, file,..) all newtypes will return false from this method.

Please note that this flag is related to the DFContainer remove(..) method's argument called destroyArtefacts. It has also meaning also only for some types and some implementations of DFItems.

getOptions

DFNewTypeOptions getOptions()

Returns:

The options of new object creation. This object should have BeanInfo and customizer to display it to user. Can also returns null if there are no options for the DFNewType.

This method returns always the same instance of options, so be careful if you modify it, the new settings will be used in create method.

isForCreatingSingleItem

boolean isForCreatingSingleItem()

Test the type of newtype.

Returns:

True if create method return only one DFItem (returned Collection's size will be 1), false means this class is going to create more DFItems at once.

create

Collection<E> create(DFEnvironmentRW env)

Create one or more new DFItems is one step. The returned object(s) is fully initialized and added to its parent (including creation all underlayed artefacts). If you call this method when options are invalid create method will fail.