Oxygen XML Editor 16.1 Author API

ro.sync.ecss.extensions.api.component
Class AuthorComponentFactory

java.lang.Object
  extended by ro.sync.ecss.extensions.api.component.AuthorComponentFactory
All Implemented Interfaces:
MathFlowConfigurator, ReferencesCustomizer

@API(type=NOT_EXTENDABLE,
     src=PRIVATE)
public class AuthorComponentFactory
extends java.lang.Object
implements ReferencesCustomizer, MathFlowConfigurator

This factory creates author components.

The recommended way to license the author component is:

  1. Set up a floating license servlet, as explained here
  2. Let each user paste their named user license key in the License Key Dialog displayed automatically when no license information is provided to the factory.

Here is a small sample showing how to load an XML document into an Author page. For more samples see the sample projects available in the SDK. Read about accessing the SDK API and samples here.
           // These two zips should be packed in some jar files from the classpath.
           URL frameworksZipURL = Reviewer.class.getResource("/frameworks.zip");  
           URL optionsZipURL = Reviewer.class.getResource("/options.zip");
     
           // Getting the component factory
           AuthorComponentFactory factory = AuthorComponentFactory.getInstance();
           factory.init(new URL[] {frameworksZipURL}, optionsZipURL, null, null, 
               // A null license key triggers the display of the license key dialog.
               // You can use a floating license servlet by invoking other init methods. 
               null);
     
           // Create the AuthorComponent provider
           EditorComponentProvider componentProvider = factory.createEditorComponentProvider(
               new String[] { EditorPageConstants.PAGE_AUTHOR },
               // The initial page
               EditorPageConstants.PAGE_AUTHOR);
     
           // This is the Author API starting point
           // You can access the document, selection, move caret, perform edits, etc..
           WSAuthorComponentEditorPage authorPage = (WSAuthorComponentEditorPage) componentProvider.getWSEditorAccess()
               .getCurrentPage();
           
           // Load a document.
           URL url = new File("D:/projects/eXml/samples/personal.xml").toURI().toURL();
           Reader reader = new InputStreamReader(url.openStream(), "UTF-8");     
           componentProvider.load(url, reader);
           
           // Show the component in a frame.
           JFrame frame = new JFrame("Author Component Sample Reviewer Application");
           frame.setSize(600, 400);
           frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
           frame.getContentPane().add(componentProvider.getEditorComponent());
           frame.setVisible(true);
 


Constructor Summary
AuthorComponentFactory()
           
 
Method Summary
 void addDITAMapTreeTargetInformationProvider(java.lang.String protocol, TopicRefTargetInfoProvider targetInformationProvider)
          Add a provider which can resolve certain information for each topic ref, without the component needing to parse that topic reference.
 void addInputURLChooserCustomizer(InputURLChooserCustomizer inputURLChooserCustomizer)
          Adds a customizer which can modify the list of "Browse" actions.
 void addRelativeReferencesResolver(java.lang.String protocol, RelativeReferenceResolver resolver)
          Add a relative reference resolver for a certain URL protocol.
 AuthorComponentProvider createAuthorComponentProvider()
          Deprecated. Please use ro.sync.ecss.extensions.api.component.AuthorComponentFactory.createEditorComponentProvider(String[], String) instead.
 DITAMapTreeComponentProvider createDITAMapTreeComponentProvider()
          Creates a new DITA Map tree component provider.
 EditorComponentProvider createEditorComponentProvider(java.lang.String[] allowedPages, java.lang.String initialPage)
          Creates a new author component
 void dispose()
          It is advisable to call this method when the Author Component Factory is no longer in use.
 void disposeAuthorComponentProvider(AuthorComponentProvider provider)
          Deprecated. Please use ro.sync.ecss.extensions.api.component.AuthorComponentFactory.disposeEditorComponentProvider() instead.
 void disposeDITAMapComponentProvider(DITAMapTreeComponentProvider provider)
          Remove the handlers the factory has to the component used to notify for changes.
 void disposeEditorComponentProvider(EditorComponentProvider provider)
          Remove the handlers the factory has to the component used to notify for changes.
static AuthorComponentFactory getInstance()
          Get the singleton instance.
 java.util.List<MenuBarCustomizer> getPluginMenubarCustomizers()
          Get the menu bar customizers which were added by all the installed plugins.
 java.util.List<ToolbarComponentsCustomizer> getPluginToolbarCustomizers()
          Get the toolbar customizers which were added by all installed plugins.
 java.util.List<ViewComponentCustomizer> getPluginViewCustomizers()
          Get the view customizers which were added by all the installed plugins.
 PluginWorkspace getPluginWorkspace()
          Get access to API used to control the created editor components.
 ro.sync.azcheck.ui.SpellCheckOptions getSpellCheckOptions()
          Get the spell check options which are currently used for the components.
 UtilAccess getUtilAccess()
          Get access to utility methods.
 WorkspaceUtilities getWorkspaceUtilities()
          Get access to various workspace utilities.
 XMLUtilAccess getXMLUtilAccess()
          Access to XML utilities.
 void init(java.net.URL[] frameworksZIPURLs, java.net.URL optionsZipURL, java.net.URL appletCodeBase, java.lang.String appletID, java.lang.String licenseKey)
          This method should get called as soon as possible before calling any other methods from this class.
 void init(java.net.URL[] frameworksZIPURLs, java.net.URL optionsZipURL, java.net.URL appletCodeBase, java.lang.String appletID, java.lang.String serverHost, int serverPort)
          This method should get called as soon as possible before calling any other methods from this class.
 void init(java.net.URL[] frameworksZIPURLs, java.net.URL optionsZipURL, java.net.URL appletCodeBase, java.lang.String appletID, java.lang.String licenseKey, java.lang.String licenseHost, int licensePort)
          Deprecated. Use {init(URL[], URL, URL, String, String, LicenseServerInformation)} or {init(URL[], URL, URL, String, String)} instead.
 void init(java.net.URL[] frameworksZIPURLs, java.net.URL optionsZipURL, java.net.URL appletCodeBase, java.lang.String appletID, java.lang.String servletURL, java.lang.String userName, java.lang.String password)
          This method should get called as soon as possible before calling any other methods from this class.
 void setDITAKeyDefinitionManager(KeyDefinitionManager keyDefitionManager)
          By default key definitions are gathered from DITA Maps opened in the DITA Maps Manager.
 void setMathFlowFixedLicenseFile(java.io.File licenseFile)
          Set the path to a license file.
 void setMathFlowFixedLicenseKeyForComposer(java.lang.String fixedKey)
          Set a fixed key for licensing the MathFlow composer used to view embedded MathML equations.
 void setMathFlowFixedLicenseKeyForEditor(java.lang.String fixedKey)
          Set a fixed key for licensing the MathFlow editor dialog used to edit embedded MathML equations.
 void setMathFlowInstallationFolder(java.io.File installationFolder)
          Set the path to the MathFlow installation folder.
 void setObjectProperty(java.lang.String key, java.lang.Object value)
          Sets a property in the Oxygen preferences.
 void setOpenURLHandler(OpenURLHandler openURLHandler)
          Set a handler which will be notified when an URL should be opened.
 void setSpellCheckOptions(ro.sync.azcheck.ui.SpellCheckOptions newSpellCheckOptions)
          Set the spell check options which are currently used for the components.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AuthorComponentFactory

public AuthorComponentFactory()
Method Detail

getInstance

public static AuthorComponentFactory getInstance()
Get the singleton instance.

Returns:
The singleton instance.

dispose

public void dispose()
It is advisable to call this method when the Author Component Factory is no longer in use. For example, if the author component is using a floating license, this method should get called in the applet when the destroy() callback is received in order to quickly release the license to the license server.

Since:
13.2

init

@Deprecated
public void init(java.net.URL[] frameworksZIPURLs,
                            java.net.URL optionsZipURL,
                            java.net.URL appletCodeBase,
                            java.lang.String appletID,
                            java.lang.String licenseKey,
                            java.lang.String licenseHost,
                            int licensePort)
          throws AuthorComponentException
Deprecated. Use {init(URL[], URL, URL, String, String, LicenseServerInformation)} or {init(URL[], URL, URL, String, String)} instead.

This method should get called as soon as possible before calling any other methods from this class. Initialize the component. Will have effect only once.

Parameters:
frameworksZIPURLs - The set of ZIPs which contain the frameworks
optionsZipURL - URL to the options ZIP.
appletCodeBase - Code base when run from an applet, can be null when using the author component in a standalone application
appletID - ID when run from Applet, can be null, used to store the frameworks associated with the applet.
licenseKey - The license key to use with the Oxygen Author component
licenseHost - If license key is missing, the license can be floating and the license host and port can be specified, else they are ignored
licensePort - If license key is missing, the license can be floating and the license host and port can be specified, else they are ignored
Throws:
AuthorComponentException

init

public void init(java.net.URL[] frameworksZIPURLs,
                 java.net.URL optionsZipURL,
                 java.net.URL appletCodeBase,
                 java.lang.String appletID,
                 java.lang.String licenseKey)
          throws AuthorComponentException
This method should get called as soon as possible before calling any other methods from this class. Initialize the component. Will have effect only once.

Parameters:
frameworksZIPURLs - The set of ZIPs which contain the frameworks
optionsZipURL - URL to the options ZIP.
appletCodeBase - Code base when run from an applet, can be null when using the author component in a standalone application
appletID - ID when run from Applet, can be null, used to store the frameworks associated with the applet.
licenseKey - The license key to use with the Oxygen Author component
Throws:
AuthorComponentException

init

public void init(java.net.URL[] frameworksZIPURLs,
                 java.net.URL optionsZipURL,
                 java.net.URL appletCodeBase,
                 java.lang.String appletID,
                 java.lang.String serverHost,
                 int serverPort)
          throws AuthorComponentException
This method should get called as soon as possible before calling any other methods from this class. Initialize the component. Will have effect only once.

Parameters:
frameworksZIPURLs - The set of ZIPs which contain the frameworks
optionsZipURL - URL to the options ZIP.
appletCodeBase - Code base when run from an applet, can be null when using the author component in a standalone application
appletID - ID when run from Applet, can be null, used to store the frameworks associated with the applet.
serverHost - The license key to use with the Oxygen Author component
serverPort - If license key is missing, the license can be floating and the license server information can be specified, else they are ignored
Throws:
AuthorComponentException
Since:
12.1

init

public void init(java.net.URL[] frameworksZIPURLs,
                 java.net.URL optionsZipURL,
                 java.net.URL appletCodeBase,
                 java.lang.String appletID,
                 java.lang.String servletURL,
                 java.lang.String userName,
                 java.lang.String password)
          throws AuthorComponentException
This method should get called as soon as possible before calling any other methods from this class. Initialize the component. Will have effect only once.

Parameters:
frameworksZIPURLs - The set of ZIPs which contain the frameworks
optionsZipURL - URL to the options ZIP.
appletCodeBase - Code base when run from an applet, can be null when using the author component in a standalone application
appletID - ID when run from Applet, can be null, used to store the frameworks associated with the applet.
servletURL - The URL to connect to a HTTP license server
userName - User name to connect to the license server.
password - Password to connect to the license server.
Throws:
AuthorComponentException
Since:
12.1

setObjectProperty

public void setObjectProperty(java.lang.String key,
                              java.lang.Object value)
Sets a property in the Oxygen preferences.

Parameters:
key - The key from the Oxygen options
value - Value for the key.

createEditorComponentProvider

public EditorComponentProvider createEditorComponentProvider(java.lang.String[] allowedPages,
                                                             java.lang.String initialPage)
                                                      throws AuthorComponentException
Creates a new author component

Parameters:
allowedPages - The pages which will be used in the editor. One of the constant fields: EditorPageConstants.PAGE_TEXT, EditorPageConstants.PAGE_AUTHOR, EditorPageConstants.PAGE_GRID
initialPage - The initial page in which the component will edit.
Returns:
the new author component
Throws:
AuthorComponentException
Since:
14.2

createAuthorComponentProvider

@Deprecated
public AuthorComponentProvider createAuthorComponentProvider()
                                                      throws AuthorComponentException
Deprecated. Please use ro.sync.ecss.extensions.api.component.AuthorComponentFactory.createEditorComponentProvider(String[], String) instead.

Creates a new author component

Returns:
the new author component
Throws:
AuthorComponentException

createDITAMapTreeComponentProvider

public DITAMapTreeComponentProvider createDITAMapTreeComponentProvider()
                                                                throws AuthorComponentException
Creates a new DITA Map tree component provider. Provides access to showing a DITA Map URL in a tree-like fashion (like the DITA Maps Manager view).

Returns:
the new DITA Map tree component provider.
Throws:
AuthorComponentException
Since:
14

disposeAuthorComponentProvider

@Deprecated
public void disposeAuthorComponentProvider(AuthorComponentProvider provider)
Deprecated. Please use ro.sync.ecss.extensions.api.component.AuthorComponentFactory.disposeEditorComponentProvider() instead.

Remove the handlers the factory has to the component used to notify for changes. It is important to call this method when creating multiple author components in a multiple editor component where editors are sometimes closed. When an editor is closed, this method should get called in order to avoid memory leaks.

Parameters:
provider - The provider to release.

disposeEditorComponentProvider

public void disposeEditorComponentProvider(EditorComponentProvider provider)
Remove the handlers the factory has to the component used to notify for changes. It is important to call this method when creating multiple author components in a multiple editor component where editors are sometimes closed. When an editor is closed, this method should get called in order to avoid memory leaks.

Parameters:
provider - The provider to release.

disposeDITAMapComponentProvider

public void disposeDITAMapComponentProvider(DITAMapTreeComponentProvider provider)
Remove the handlers the factory has to the component used to notify for changes. It is important to call this method when creating multiple DITA Map components in a multiple editor component where editors are sometimes closed. When an editor is closed, this method should get called in order to avoid memory leaks.

Parameters:
provider - The provider to release.

getSpellCheckOptions

public ro.sync.azcheck.ui.SpellCheckOptions getSpellCheckOptions()
Get the spell check options which are currently used for the components.

Returns:
the spell check options which are currently used for the components.

setSpellCheckOptions

public void setSpellCheckOptions(ro.sync.azcheck.ui.SpellCheckOptions newSpellCheckOptions)
Set the spell check options which are currently used for the components. All options can be changed except the spell checker which is fixed to Hunspell.

Parameters:
newSpellCheckOptions - The new spell check options to set.

setOpenURLHandler

public void setOpenURLHandler(OpenURLHandler openURLHandler)
Set a handler which will be notified when an URL should be opened. For example the user clicked a link in the Author page.

Parameters:
openURLHandler - The open URLs handler.
Since:
12.2

addInputURLChooserCustomizer

public void addInputURLChooserCustomizer(InputURLChooserCustomizer inputURLChooserCustomizer)
Description copied from interface: ReferencesCustomizer
Adds a customizer which can modify the list of "Browse" actions. These actions are available in Oxygen, in any control or dialog that contains an URL input box.
IMPORTANT This customizer must be set early, when the plugin extension's applicationStarted method gets called or after the AuthorComponentFactory was initialized (if running the Author component).
Example: If a CMS developer wants the user to choose the URL from their custom CMS chooser then it will add a new action (possibly removing the others). When the new action gets called the custom code shows the custom chooser and at the end it can call the ro.sync.exml.workspace.api.standalone.InputURLChooser interface to set the new URL in the combo box.

Specified by:
addInputURLChooserCustomizer in interface ReferencesCustomizer
Parameters:
inputURLChooserCustomizer - The input URL chooser customizer.
Since:
13
See Also:
ReferencesCustomizer.addInputURLChooserCustomizer(ro.sync.exml.workspace.api.standalone.InputURLChooserCustomizer)

addRelativeReferencesResolver

public void addRelativeReferencesResolver(java.lang.String protocol,
                                          RelativeReferenceResolver resolver)
Description copied from interface: ReferencesCustomizer
Add a relative reference resolver for a certain URL protocol. This method can be used by a CMS implementor to take control over the way Oxygen is computing relative references for a certain URL protocol. For example when inserting in a DITA Topic a reference to an image Oxygen will try to make the reference relative to the current XML document. If the DITA Topic is opened using your custom URL protocol you can take control over they way in which the relative path is computed.

Specified by:
addRelativeReferencesResolver in interface ReferencesCustomizer
Parameters:
protocol - The URL protocol for which you want to take control over the relativization.
resolver - The custom resolver.
Since:
13
See Also:
ReferencesCustomizer.addRelativeReferencesResolver(java.lang.String, ro.sync.exml.workspace.api.util.RelativeReferenceResolver)

addDITAMapTreeTargetInformationProvider

public void addDITAMapTreeTargetInformationProvider(java.lang.String protocol,
                                                    TopicRefTargetInfoProvider targetInformationProvider)
Add a provider which can resolve certain information for each topic ref, without the component needing to parse that topic reference.

Parameters:
protocol - The protocol for which the provider is registered
targetInformationProvider - The topic reference target information provider provider.
Since:
14

setMathFlowFixedLicenseKeyForEditor

public void setMathFlowFixedLicenseKeyForEditor(java.lang.String fixedKey)
Set a fixed key for licensing the MathFlow editor dialog used to edit embedded MathML equations.

Specified by:
setMathFlowFixedLicenseKeyForEditor in interface MathFlowConfigurator
Parameters:
fixedKey - The fixed key. The key needs to be obtained from MathFlow: http://dessci.com/ and has the following format: MFSCKKK-KKKKKK-KKKKK If no editor key will be given then MathFlow will be used neither for editing nor for rendering.
Since:
14

setMathFlowFixedLicenseKeyForComposer

public void setMathFlowFixedLicenseKeyForComposer(java.lang.String fixedKey)
Set a fixed key for licensing the MathFlow composer used to view embedded MathML equations.

Specified by:
setMathFlowFixedLicenseKeyForComposer in interface MathFlowConfigurator
Parameters:
fixedKey - The fixed key. The key needs to be obtained from MathFlow: http://dessci.com/ and has the following format: MFSEKKK-KKKKKK-KKKKK If no composer key will be given then the fallback for rendering will be the Apache JEuclid library.
Since:
14

setMathFlowFixedLicenseFile

public void setMathFlowFixedLicenseFile(java.io.File licenseFile)
Set the path to a license file.

Specified by:
setMathFlowFixedLicenseFile in interface MathFlowConfigurator
Parameters:
licenseFile - The path to the MathFlow license file. If the file contains both a license for the composer and for the editor, then both rendering and editing is supported. If the file contains a license only for the editor, rendering will be done using the open source JEuclid library.
Since:
16

*********************************
EXPERIMENTAL - Subject to change
********************************

Please note that this API is not marked as final and it can change in one of the next versions of the application. If you have suggestions, comments about it, please let us know.


setMathFlowInstallationFolder

public void setMathFlowInstallationFolder(java.io.File installationFolder)
Set the path to the MathFlow installation folder.

Specified by:
setMathFlowInstallationFolder in interface MathFlowConfigurator
Parameters:
installationFolder - The MathFlow installation folder
Since:
16

*********************************
EXPERIMENTAL - Subject to change
********************************

Please note that this API is not marked as final and it can change in one of the next versions of the application. If you have suggestions, comments about it, please let us know.


getXMLUtilAccess

public XMLUtilAccess getXMLUtilAccess()
Access to XML utilities.

Returns:
Access to XML utilities.
Since:
14.2

getUtilAccess

public UtilAccess getUtilAccess()
Get access to utility methods.

Returns:
access to utility methods.
Since:
14.2

getPluginToolbarCustomizers

public java.util.List<ToolbarComponentsCustomizer> getPluginToolbarCustomizers()
Get the toolbar customizers which were added by all installed plugins.

Returns:
Returns the toolbar customizers which were added by all installed plugins.
Since:
14.2

getPluginViewCustomizers

public java.util.List<ViewComponentCustomizer> getPluginViewCustomizers()
Get the view customizers which were added by all the installed plugins.

Returns:
Returns the view customizers which were added by all installed plugins.
Since:
14.2

getPluginMenubarCustomizers

public java.util.List<MenuBarCustomizer> getPluginMenubarCustomizers()
Get the menu bar customizers which were added by all the installed plugins.

Returns:
Returns the menu bar customizers which were added by all installed plugins.
Since:
14.2

setDITAKeyDefinitionManager

public void setDITAKeyDefinitionManager(KeyDefinitionManager keyDefitionManager)
By default key definitions are gathered from DITA Maps opened in the DITA Maps Manager. This API can be used by the developer to take control over the key definitions which will be used to resolve keyrefs and conkeyrefs for topics opened in the Author page.

Parameters:
keyDefitionManager - The key definition manager
Since:
15

getWorkspaceUtilities

public WorkspaceUtilities getWorkspaceUtilities()
Get access to various workspace utilities.

Returns:
Access to various workspace utilities.
Since:
15

getPluginWorkspace

public PluginWorkspace getPluginWorkspace()
Get access to API used to control the created editor components. This API may not implement all the functionality available in the standalone editor.

Returns:
Returns the pluginWorkspace.
Since:
16

*********************************
EXPERIMENTAL - Subject to change
********************************

Please note that this API is not marked as final and it can change in one of the next versions of the application. If you have suggestions, comments about it, please let us know.


Oxygen XML Editor 16.1 Author API

© Copyright SyncRO Soft SRL 2002 - 2014. All rights reserved.