ilog.views.appframe
Class IlvApplication

java.lang.Object
  extended by ilog.views.appframe.IlvApplication
All Implemented Interfaces:
IlvPropertyManager

public class IlvApplication
extends Object
implements IlvPropertyManager

An application centralizes all the services that are provided with the JAppFrame project.
It is mandatory that all the applications that use this project initialize an IlvApplication instance, since all the JAppFrame components initialize themselves using an instance of IlvApplication. For example, an IlvMenuBar reads the definition of its menu items from the settings of the application and internationalizes the text displayed by its menu items using the internationalization services of the application.

Services provided by the application are:

Common Services
Gather the management of the settings, internationalization services, and resolution of URLs.

Document/View The application is the key component of the JAppFrame Document/View architecture. As illustrated in the following figure, it handles both the document templates and the main window.

The application is involved in all the steps of the life cycle of documents. It creates the documents, gives access to the active document, and allows for saving and closing documents.

Swing actions
The application centralizes all the services relative to Swing actions. When initializing, the application creates IlvAction instances for each <action> root setting element it has selected from its settings. New actions can be added to the application with the method addAction(javax.swing.Action) and removed with the method removeAction(javax.swing.Action).

The JAppFrame project has changed the semantic of Swing actions. They no longer handle the events emitted by menu items or buttons associated with them. They only contain display properties that allow for creating associated menu items or buttons. As all those properties can be specified from the settings of the action - as described for the IlvAction class - it is no longer necessary to implement action classes.
The application delegates the processing of action events to its registered action handlers by implementing the interface ActionHandler. An action handler is responsible for both processing action events and updating the properties of the action. From the lowest to the highest priority, the application automatically registers the following action handlers:

It is also possible to register new action handlers with the method addActionHandler(ilog.views.appframe.event.ActionHandler) and to remove them with the method removeActionHandler(ilog.views.appframe.event.ActionHandler).

Processing action events
From the highest to the lowest priority, action handlers are required to process the action events. The first action handler that processes the event stops the calling chain.

Updating actions
As in processing action events, the action handlers are required to update the state of the actions, from the highest to the lowest priority. The first action handler that succeeds in updating the action stops the calling chain.
Updates of actions are automatically triggered when the application initializes and each time the active view of the application changes. However, it is possible to trigger the application update mechanism for one or more actions with the methods updateAction(java.lang.String), updateActionsByCategory(java.lang.String) and updateActions().

Since:
JViews 5.5

Field Summary
static String CLOSE_ALL_DOCUMENTS_CMD
          Action command key for the action that closes all the open documents.
static String CLOSE_DOCUMENT_CMD
          Action command key for the action that closes the active document.
static String EXIT_CMD
          Action command key for the action that exits the application.
static String ICON_PROPERTY
          Bound property name for the icon of the application.
static String MAIN_WINDOW_PROPERTY
          Bound property name for the main window of the application.
static String MENU_BAR_PROPERTY
          Bound property name for the menu bar of the application main window.
static String NEW_DOCUMENT_CMD
          Action command key for the action that creates a new document.
static String NEW_DOCUMENT_ON_LAST_TEMPLATE_CMD
          Action command key for the action that creates a new document of the same type as the type of the last document created with the newDocument() method.
static String OPEN_DOCUMENT_CMD
          Action command key for the action that opens a document.
static int OPEN_FILE_MUST_EXIST
          File chooser constant that determines whether the file selected in the file chooser should exist.
static int OPEN_MODE
          File chooser constant that specifies that the file chooser is displayed for opening a file.
static int OPEN_MULTIPLE_FILES
          File chooser constant that determines whether multiple files can be selected within the file chooser.
static String REVERT_DOCUMENT_CMD
          Action command key for the Revert Document action.
static String SAVE_ALL_DOCUMENTS_CMD
          Action command key for the action that saves all modified documents.
static String SAVE_AS_DOCUMENT_CMD
          Action command key for the Save as action.
static int SAVE_AS_MODE
          File chooser constant that specifies that the file chooser is displayed for changing a filename while processing a SaveAs action.
static String SAVE_DOCUMENT_CMD
          Action command key for the Save action.
static int SAVE_MODE
          File chooser constant that specifies that the file chooser is displayed for changing a filename.
static String SETTINGS_TYPE
          Type of settings element providing the settings of the application, such as its title or icon.
static String STATUS_BAR_PROPERTY
          Bound property name for the status bar of the application main window.
static String STATUS_MESSAGE
          Name of the message to send to the application to make a string message appear in the status bar of the main window of the application.
static String TITLE_PROPERTY
          Bound property name for the title of the application.
 
Constructor Summary
IlvApplication()
          Creates a new IlvApplication with the name Default.
IlvApplication(String applicationName)
          Creates a new application with the specified name.
IlvApplication(String[] args)
          Creates the application with the specified command line parameters.
IlvApplication(String name, String[] args)
          Creates a new IlvApplication with the specified command line parameters and the specified name.
 
Method Summary
 void addAction(Action action)
          Adds an action to the actions managed by the application.
 void addActionHandler(ActionHandler handler)
          Adds the specified action handler to receive action events.
 void addApplicationListener(ApplicationListener listener)
          Adds an application listener for receiving application events.
 void addApplicationListener(String templateName, ApplicationListener listener)
          Adds an application listener to receive application events for a specific document template.
 void addClassLoader(ClassLoader classLoader)
          Adds the specified classLoader to the list of class loaders managed by the application for loading classes and finding resources.
 void addDocumentTemplate(IlvDocumentTemplate docTemplate)
          Adds the specified document template to the application.
 void addLocaleSettingsListener(LocaleSettingsListener listener)
          Adds a locale setting listener to listen to changes that occur to the locale of the application.
 void addMessageListener(MessageListener listener, String name)
          Adds the specified message listener to receive message event sent to the application.
 void addPropertyChangeListener(PropertyChangeListener listener)
          Adds a listener that listens to the changes in the properties of this application.
 void addResourceBundle(ResourceBundle bundle)
          Adds the specified resource bundle to the list of resource bundles managed by this application.
 ResourceBundle addResourcePropertyFile(String baseName)
          Adds the specified resource bundle to the list of resource bundles managed by the application.
 boolean addSettings(IlvSettings settings)
          Adds new settings to the application.
 void addSettingsListener(SettingsListener listener)
          Adds a settings listener to listen to settings events.
 void addURLResolver(IlvURLResolver resolver)
          Adds the specified URL resolver to the application.
 IlvXMLSettings addXMLSettings(String filename)
          Adds XML settings to the application.
 IlvXMLSettings addXMLSettings(URL url)
          Adds the XML settings file with the specified URL.
 HashMap applyCursor(Cursor cursor)
          Sets a new cursor on all windows.
 void attachDocument(IlvDocument parentDocument, IlvDocument document)
          Attaches the specified document to the specified parentDocument.
 boolean canCreateDocument(Object userData)
          Determines whether the application can create a document for the specified userData.
 boolean close(boolean force)
          Tries to end the application.
 boolean closeActiveDocument(boolean mdiDocument)
          Closes the current active document in the application.
 boolean closeAllDocuments(boolean endSession)
          Closes all the documents opened in the application.
 boolean closeDocument(IlvDocument document, boolean force)
          Closes the specified document in the application.
 void commitSettingsChanges()
          Commits the changes that occurred on the application settings to the user settings.
protected  IlvDocumentTemplate createDocumentTemplate(String name)
          Deprecated. As of JViews 6.0, replaced with createDocumentTemplate(java.lang.String, ilog.views.appframe.settings.IlvSettingsElement). This method is now invoked from this last method.
protected  IlvDocumentTemplate createDocumentTemplate(String name, IlvSettingsElement element)
          Creates a document template with the specified name.
 void detachDocument(IlvDocument parentDocument, IlvDocument document)
          Detaches the specified document from the specified parentDocument.
 IlvDocument findDocument(String pathname)
          Finds an open document with the specified pathname.
protected  void fireApplicationEvent(ApplicationEvent event)
          Notifies all the application listeners registered with the application that the specified application event has occurred.
protected  void fireLocaleSettingsEvent(LocaleSettingsEvent event)
          Fires the specified locale setting event to the locale setting listeners added to the application.
protected  void firePropertyChange(String propertyName, Object oldValue, Object newValue)
          Support method for notifying changes on the application properties: if oldValue and newValue are equal, this method does nothing.
 String getAbbreviateForm(URL url)
          Returns the abbreviated form of the specified URL.
 Action getAction(String command)
          Retrieves an action by its command key.
 ActionHandler[] getActionHandlers(String actionCommand)
          Returns an array of action handlers which can process actions with the specified actionCommand.
 IlvDocument getActiveDocument(boolean mdiDocument)
          Returns the document currently active in the application.
 IlvDocumentView getActiveView(boolean mdiDocument)
          Returns the document view currently active in the application.
 IlvViewContainer getActiveViewContainer()
          Returns the container of the active document view.
 Applet getApplet()
          Returns the main window of the application as an applet.
 Class getClassForName(String classname)
          Retrieves a class for the specified classname.
 ClassLoader getClassLoader()
          Returns the class loader associated with the application.
protected  String getDefaultUserSettingsPathname()
          Returns the default pathname of the XML file that contains the settings for the current application user.
 URL getDocumentBase()
          Returns the document base URL.
 IlvDocumentTemplate getDocumentTemplate(int index)
          Returns the document template at the specified storage index in the set of document templates managed by this application.
 IlvDocumentTemplate getDocumentTemplate(String name)
          Retrieves the document template with the specified name.
 int getDocumentTemplateCount()
          Returns the number of document templates managed by this application.
 String getFormattedString(String format, Object[] params)
          Returns the string resulting from the formatting of the specified format with the parameters contained in the params array of objects.
 ImageIcon getImageIcon()
          Returns the icon of the application.
 ImageIcon getImageIcon(String filename)
          Returns an image icon for the specified filename.
 Locale getLocale()
          Returns the locale of the application.
 Component getMainComponent()
          Returns the main window of the application as a Component.
 Container getMainContainer()
          Returns the main window of the application as a container.
 IlvMainWindow getMainWindow()
          Returns the main window associated with the application.
 String getName()
          Returns the name of the application.
 IlvDocument[] getOpenDocuments()
          Returns all the open documents in the application.
 IlvDocument[] getOpenDocuments(IlvDocumentTemplate documentTemplate)
          Returns all the documents open in the application for the specified documentTemplate.
 int getOpenedDocumentCount()
          Returns the number of open documents in the application.
 Object getProperty(String key)
          Returns the property of the application with the specified key.
 IlvRecentFileList getRecentFileList()
          Returns the recent file list used by the application to store the Most Recently Used files.
 String getRecentOpenedFile(int index)
          Returns the pathname at the specified storage index in the Most Recently Used file list managed by the application.
 int getRecentOpenedFileCount()
          Returns the number of pathnames stored in the Most Recently Used file list of the application.
 IlvResourceBundleManager getResourceBundleManager()
          Returns the resource bundle manager associated with the locale of this application.
 IlvSettings[] getSettings()
          Returns the settings managed by this application.
 IlvSettings getSettings(String name)
          Finds the settings with the specified name.
 IlvSettingsManager getSettingsManager()
          Returns the settings manager that manages all the settings of the application.
 String getSoftwareProvider()
          Returns the software provider name.
 IlvSplashWindow getSplashWindow()
          Returns the splash window currently displayed while the application is initializing.
 String getString(String key)
          Retrieves a string resource for the specified key.
 String getTitle()
          Returns the title of the application.
 IlvURLResolverManager getURLResolverManager()
          Returns the URL resolver manager used by the application to resolve URLs.
 URL getUserHomeDirectory()
          Returns the home directory of the current application user.
 String getUserSettingsSubDirectory()
          Returns the subdirectory that is used for constructing the pathname of the XML file containing the user settings for the current application user.
 URL getUserSettingsURL()
          Returns the URL of the XML file containing the settings of the current application user.
 boolean initialize()
          Initializes the application.
 void initializeFileChooser(JFileChooser fileChooser, String initialPathName, int mode, IlvFileDocumentTemplate fileTemplate)
          Initializes a file chooser dialog.
 boolean isApplet()
          Determines whether the main window of this application is an applet.
 boolean isInitialized()
          Determines whether the application is initialized.
 boolean isValidDocumentFile(String pathname)
          Returns if the given pathname corresponds to a file that is accepted by this application.
 IlvDocument newDocument()
          Creates a new document.
 IlvDocument newDocument(IlvDocumentTemplate docTemplate, boolean createViews, Object userData)
          Creates a new document for the specified document template.
 IlvDocument newDocument(Object userData, boolean createViews)
          Creates a new document that embeds the specified userData.
 IlvDocument newDocumentOnLastTemplate()
          Creates a new document for the same document template as the one selected in the New Document dialog box the last time it was launched.
 IlvDocument openDocument()
          Prompts for a document file name and opens the corresponding document.
 IlvDocument openDocument(IlvFileDocumentTemplate docTemplate)
          Opens a document for the specified document template.
 IlvDocument openDocumentFile(String pathname, boolean createViews, boolean addToMRU)
          Opens a document with the specified pathname.
 IlvDocument openRecentOpenedFile(int index)
          Opens or activates the document file corresponding to the pathname stored at specified index in the list of Most Recently Used files managed by the application.
protected  void quit()
          Quits the application.
 void removeAction(Action action)
          Removes an action from the list of actions managed by the application.
 void removeActionHandler(ActionHandler handler)
          Removes the specified action handler from the list of action handlers managed by the application.
 void removeApplicationListener(ApplicationListener listener)
          Removes the specified application listener, so that it no longer receives application events.
 void removeApplicationListener(String templateName, ApplicationListener listener)
          Removes the specified listener, so that it no longer receives application events.
 boolean removeClassLoader(ClassLoader classLoader)
          Removes the specified classLoader from the list of class loaders managed by the application.
 boolean removeDocumentTemplate(IlvDocumentTemplate documentTemplate)
          Removes the specified documentTemplate from the list of document templates managed by the application.
 boolean removeLocaleSettingsListener(LocaleSettingsListener listener)
          Removes the specified locale setting listener from the list of listeners managed by the application.
 void removeMessageListener(MessageListener listener)
          Removes the specified message listener from the list of message listeners managed by the application.
 void removePropertyChangeListener(PropertyChangeListener listener)
          Removes the specified listener from the list of PropertyChange listeners managed by the application.
 ResourceBundle removeResourcePropertyFile(String baseName)
          Removes the resource bundle with the specified baseName from the application.
 boolean removeSettings(IlvSettings settings)
          Removes the specified settings from the list of settings stored by the application.
 boolean removeSettingsListener(SettingsListener listener)
          Removes the specified settings listener from the list of settings listeners managed by the settings manager of the application.
 boolean removeURLResolver(IlvURLResolver resolver)
          Removes the specified URL resolver from the list of resolvers managed by the application.
 URL resolveURL(String filename)
          Resolves a URL from the specified filename.
 void restoreCursor()
          Deprecated. replaced by restoreCursor(java.util.HashMap)
 void restoreCursor(HashMap targetComponents)
          Restores the saved cursors on components.
 boolean saveActiveDocument(boolean mdiDocument)
          Saves the document currently active in the application.
 boolean saveAllDocuments()
          Saves all the modified documents open in the application.
 boolean saveAsActiveDocument(boolean mdiDocument)
          Saves the active document under another file name.
 boolean saveDocument(IlvDocument document)
          Saves the specified document.
 boolean saveDocument(String pathname)
          Saves the document with the specified pathname.
 boolean saveDocumentModifications(IlvDocument document)
          Saves the modifications of the specified document.
 IlvSettingsElement[] select(IlvSettingsQuery query)
          Returns the settings elements selected by the specified query.
 IlvSettingsElement[] select(IlvSettingsQuery query, IlvSettingsElement[] contextElements)
          Returns the settings elements selected by the specified query starting from the specified settings elements.
 IlvSettingsElement[] select(String type, IlvSettingsElement[] contextElements)
          Returns the settings elements selected by the specified query parameters.
 IlvSettingsElement selectElement(IlvSettingsQuery query)
          Returns the first settings element selected by the specified query.
 IlvSettingsElement selectElement(String type, String attributeName, Object attributeValue)
          Returns the first settings element selected by the specified query parameters.
 void sendActionEvent(ActionEvent e)
          Sends an action event to the action handlers of the application.
 void sendActionEvent(String actionCommand)
          Sends an action event to the action listeners of the application.
 void sendMessage(String targetName, MessageEvent messageEvent)
          Sends the specified message event to all the message listeners registered with the application.
 void sendMessage(String targetName, Object source, String messageName, Object[] params)
          Sends the message messageName to the target targetName with the parameters params.
 void setActiveDocument(IlvDocument document, IlvDocumentView view, boolean mdiDocument)
          Sets the active document of the application.
 void setActiveView(IlvDocumentView view, boolean mdiDocument)
          Sets the active document view of this application.
 void setCursor(Cursor cursor)
          Deprecated. replaced by applyCursor(java.awt.Cursor) less prone to memory leaks
 void setDocumentBase(URL documentBase)
          Sets the document base URL of the application.
 void setImageIcon(ImageIcon icon)
          Sets the icon of the application to the specified icon.
 void setLocale(Locale locale)
          Sets the locale for the application.
 void setMainWindow(IlvMainWindow window)
          Sets the main window of the application.
 void setName(String name)
          Sets the name of the application.
 Object setProperty(String key, Object value)
          Sets one of the properties of the application using the associated key.
 void setResourceBundleManager(IlvResourceBundleManager manager)
          Sets the resource bundle manager that will manage the resource bundles of the application.
 void setSoftwareProvider(String name)
          Sets the software provider.
 void setSplashWindow(IlvSplashWindow splashWindow)
          Sets a splash window for the application.
 void setTitle(String title)
          Sets the title of the application to the specified string.
 void setUserHomeDirectory(URL url)
          Sets the home directory for the current application user.
 void setUserSettingsSubDirectory(String subDirectory)
          Sets the sub directory that is used for constructing the pathname of the XML file containing the user settings for the current application user.
 void setUserSettingsURL(URL url)
          Sets the URL that accesses the settings of the current application user.
 IlvFileChooserSelection[] showFileChooser(String initialPathName, String title, int mode, IlvFileDocumentTemplate initialTemplate, Component parent)
          Displays a file chooser dialog.
 boolean updateAction(Action action)
          Asks for the display properties of the specified action to be updated.
 boolean updateAction(String command)
          Asks for the display properties of the action with the specified command key to be updated.
 void updateActions()
          Asks for the display properties of all the actions that are represented in all of the menu bars and toolbars of the main window of the application to be updated.
 void updateActionsByCategory(String category)
          Asks for the display properties of all the actions that belong to the specified category to be updated.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CLOSE_ALL_DOCUMENTS_CMD

public static final String CLOSE_ALL_DOCUMENTS_CMD
Action command key for the action that closes all the open documents.

See Also:
Constant Field Values

CLOSE_DOCUMENT_CMD

public static final String CLOSE_DOCUMENT_CMD
Action command key for the action that closes the active document.

See Also:
Constant Field Values

OPEN_DOCUMENT_CMD

public static final String OPEN_DOCUMENT_CMD
Action command key for the action that opens a document.

See Also:
Constant Field Values

NEW_DOCUMENT_CMD

public static final String NEW_DOCUMENT_CMD
Action command key for the action that creates a new document.

See Also:
newDocument(), Constant Field Values

NEW_DOCUMENT_ON_LAST_TEMPLATE_CMD

public static final String NEW_DOCUMENT_ON_LAST_TEMPLATE_CMD
Action command key for the action that creates a new document of the same type as the type of the last document created with the newDocument() method.

See Also:
newDocumentOnLastTemplate(), Constant Field Values

SAVE_ALL_DOCUMENTS_CMD

public static final String SAVE_ALL_DOCUMENTS_CMD
Action command key for the action that saves all modified documents.

See Also:
Constant Field Values

SAVE_DOCUMENT_CMD

public static final String SAVE_DOCUMENT_CMD
Action command key for the Save action.

See Also:
Constant Field Values

SAVE_AS_DOCUMENT_CMD

public static final String SAVE_AS_DOCUMENT_CMD
Action command key for the Save as action.

See Also:
Constant Field Values

REVERT_DOCUMENT_CMD

public static final String REVERT_DOCUMENT_CMD
Action command key for the Revert Document action.

See Also:
Constant Field Values

EXIT_CMD

public static final String EXIT_CMD
Action command key for the action that exits