Changes due to improvements

1. Status bar

   Since 4.3 the older and not very flexible status bar have been replaced by a new generation of status bar as a snap-in container which contains any number of status bar snap-ins. Every component can be a snap-in by implementing the SnapIn Marker Interface. This improvement allows a flexible expandability and adaptation of the status bar appearance and functionality to customized and/or future requirements.

   As a consequence of this change the old status bar classes have reached their final EOL point.

   • com.levigo.jadice.gui.StatusBar
   • com.levigo.jadice.doctree.DocumentTreeStatusBar

   Thus they do not underly any support and are no longer part of the distribution. All status bar references should be changed to the offered alternative. If this is not possible or explicitly unwanted integrations may get the old classes as source code on demand. In this case these sources and classes may be used freely, however, they will not be supported.

   The concerned classes and methods as well as the changed way to use the new status bar will be described in the following section.

   The changes described in this section are identical for the classes com.levigo.jadice.gui.AbstractJadicePanel, com.levigo.jadice.applet.BasicAppletViewerPanel, JadiceMDI, com.levigo.jadice.doctree.viewer.ViewerPanel, com.levigo.jadice.doctree.frames.JadiceDocTreeSDISplitFrame, com.levigo.jadice.doctree.frames.JadiceDocTreeMDISplitFrame:

   • New Field

     New field:	Description:
     protected StatusBar snapInStatusBar	Protected field reference. It is strongly recommended not to use field reference in any direct way. Use the StatusBar getSnapInStatusBar() method instead. The one and only allowed access should be within the method StatusBar createSnapInStatusBar() to create and define the field access at initialization time.

   • New Method

     New method:	Description:
     protected com.levigo.jadice.gui.status.StatusBar createSnapInStatusBar()	Could be overridden to manipulate the status bar and its contained snap-ins at initialization time.

   • Method replacement

     Old method:	Alternative method:
     com.levigo.jadice.gui.StatusBar getStatusBar()	public com.levigo.jadice.gui.status.StatusBar getSnapInStatusBar()
     public void setStatusBar(final StatusBar aStatusBar)	No replacement, not used anymore. Access and changes to the status bar may take place at at initialization time with protected StatusBar createSnapInStatusBar() or at any other time with a combination of getSnapInStatusBar() and add or remove snap-ins. Addition or removal of snap-ins can be done with the well-known Container add and remove methods. Snap-in access is possible with com.levigo.jadice.gui.status.StatusBar.getSnapIn(...)

   The factory class com.levigo.jadice.gui.status.SnapInFactory can be used to obtain new standard snap-ins instances.

   • SnapIn Factory

     Factory method:	Description:
     public com.levigo.jadice.gui.status.SnapInFactory.createPageSnapIn()	Page number snap-in.
     public com.levigo.jadice.gui.status.SnapInFactory.createZoomSnapIn()	Zoom snap-in.
     public com.levigo.jadice.gui.status.SnapInFactory.createPrinterStatusSnapIn()	Printing status snap-in.
     public com.levigo.jadice.gui.status.SnapInFactory.createDocumentStatusMessageSnapIn()	Status and message snap-in.
     public com.levigo.jadice.gui.status.SnapInFactory.createTaskServiceMonitorSnapIn()	(For development or problem analysis only) Internal process activity monitor snap-in.
     public com.levigo.jadice.gui.status.SnapInFactory.createMemoryMonitorSnapIn()	(For development or problem analysis only) Heap memory consumption snap-in.

      
    

2. Search notifications

   The general search enhancements since 4.3 require update of the search notification mechanism, too. Therefore a new listener, a related adapter class and approbate event objects have been introduced as a replacement for the previous notification mechanism.

   The following sections describe the changes and replacements in detail.

   • New Classes

     New classes:	Description:
     com.levigo.jadice.addon.search.SearchRequestState	Type safe state enum for search request states. In addition to the pre 4.3 versions two new states are introduced enqueued and failed.
     com.levigo.jadice.addon.search.event.SearchRequestListener, com.levigo.jadice.addon.search.event.SearchRequestAdapter	Search request listener and approbate adapter class for listening to search progress and results.
     com.levigo.jadice.addon.search.event.AbstractSearchRequestEvent and specialized subclassed events: com.levigo.jadice.addon.search.event.SearchRequestProgressEvent com.levigo.jadice.addon.search.event.SearchRequestResultEvent com.levigo.jadice.addon.search.event.SearchRequestFailedEvent	Used for search request listeners as event transport objects when search progress or result events happen.

   • New Methods

     New method:	Description:
     com.levigo.jadice.addon.search.AbstractCharSequenceSearchRequest.getState()	Returns a com.levigo.jadice.addon.search.SearchRequestState, which indicates the current state of search request instance.
     com.levigo.jadice.addon.search.AbstractCharSequenceSearchRequest.executeSync()	Executes the search request synchronous on the called thread.

   • Class Replacements

     Pre 4.3:	Since 4.3:
     com.levigo.jadice.addon.search.SearchStateListener	com.levigo.jadice.addon.search.event.SearchRequestListener or SearchRequestAdapter
     com.levigo.jadice.addon.search.SearchResultListener	com.levigo.jadice.addon.search.event.SearchRequestListener or SearchRequestAdapter
     com.levigo.jadice.addon.search.SearchStateChangeEvent	com.levigo.jadice.addon.search.event.SearchRequestProgressEvent
     com.levigo.jadice.addon.search.SearchResultEvent	com.levigo.jadice.addon.search.event.SearchRequestResultEvent

   • Method Replacements

     Pre 4.3:	Since 4.3:
     com.levigo.jadice.addon.search.AbstractCharSequenceSearchRequest.addSearchStateListener(SearchStateListener)	com.levigo.jadice.addon.search.AbstractCharSequenceSearchRequest.addSearchRequestListener(SearchRequestListener)
     com.levigo.jadice.addon.search.AbstractCharSequenceSearchRequest.addSearchResultListener(SearchResultListener)	com.levigo.jadice.addon.search.AbstractCharSequenceSearchRequest.addSearchRequestListener(SearchRequestListener)
     com.levigo.jadice.addon.search.AbstractCharSequenceSearchRequest.removeSearchRequestListener(SearchResultListener)	com.levigo.jadice.addon.search.AbstractCharSequenceSearchRequest.addSearchRequestListener(SearchRequestListener)

Method signature update

• The following method signature of the Page class have been changed.

  Old:	New:
  com.levigo.jadice.docs.Page.getRotatedSize(RenderContext)	com.levigo.jadice.docs.Page.getRotatedSize(RenderControls)

Deprecations

The following interfaces and adapter classes have been deprecated and replaced by a new equivalent which provides more and detailed informations to a registered listener.

All references should be changed to the offered alternative.

• Deprecated Interfaces and Classes

  Deprecated class:	Alternative class:
  com.levigo.jadice.docs.DocumentListener	com.levigo.jadice.docs.event.DocumentListener2
  com.levigo.jadice.docs.DocumentListenerAdapter	com.levigo.jadice.docs.event.DocumentAdapter2
  com.levigo.jadice.docs.PageListener	com.levigo.jadice.docs.PageListener

• Deprecated Methods

  Deprecated method:	Alternative method:
  com.levigo.jadice.docs.Document.addDocumentListener(DocumentListener)	com.levigo.jadice.docs.Document.addDocumentListener2(DocumentListener2)
  com.levigo.jadice.docs.Document.removeDocumentListener(DocumentListener)	com.levigo.jadice.docs.Document.removeDocumentListener2(DocumentListener2)
  com.levigo.jadice.docs.Page.addPageListener(PageListener)	com.levigo.jadice.docs.Page.addPageListener2(PageListener2)
  com.levigo.jadice.docs.Page.removePageListener(PageListener)	com.levigo.jadice.docs.Page.removePageListener2(PageListener2)

• The following methods of the class Document have been deprecated and replaced by a type safe equivalent. All references should be changed to the offered alternative.

  Deprecated method:	Alternative method:
  com.levigo.jadice.docs.Document.getStatus()	com.levigo.jadice.docs.Document.getState()
  com.levigo.jadice.docs.Document.setStatus(int)	com.levigo.jadice.docs.Document.setState(State)

• The following methods of the class PrinterJava2 have been deprecated and replaced by a equivalent using enumeration. All references should be changed to the offered alternative.

  Deprecated method:	Alternative method:
  com.levigo.jadice.docs.printer.PrinterJava2.getReferenceBase()	com.levigo.jadice.docs.printer.PrinterJava2.getOutputReferenceBase()
  com.levigo.jadice.docs.printer.PrinterJava2.setReferenceBase(int)	com.levigo.jadice.docs.printer.PrinterJava2.setOutputReferenceBase(OutputReferenceBase)

• The following constants of the class PrinterJava2 have been deprecated and replaced by a enumeration equivalent. All references should be changed to the offered alternative.

  Deprecated constant:	Alternative enumeration:
  com.levigo.jadice.docs.printer.PrinterJava2.REFERENCE_BASE_PAPER	com.levigo.jadice.docs.printer.PrinterJava2.OutputReferenceBase.PAPER
  com.levigo.jadice.docs.printer.PrinterJava2.REFERENCE_BASE_IMAGEABLE_AREA	com.levigo.jadice.docs.printer.PrinterJava2.OutputReferenceBase.PAGEFORMAT

Deprecation Removals

• The following constants of the loader class are removed:

  Removed:

  com.levigo.jadice.docs.resource.Loader.COMPOSITE_STRUCTURE_INDEX_SEPARATOR

  com.levigo.jadice.docs.resource.Loader.COMPOSITE_STRUCTURE_PREFIX

User property support of Page, PageSegment and Document

Beginning with jadice® 4.2 there was some API cleanup regarding the methods for handling user properties of the classes com.levigo.jadice.docs.Page, com.levigo.jadice.docs.PageSegment and com.levigo.jadice.docs.Document. Before jadice® 4.2 it was allowed to supply a key of any type. This was incorrect, as there are a lot of assumptions expecting the key to be of type java.lang.String.

• The following methods are affected (the method declarations are identical in all of the three classes):

  Deprecated/Removed method:	Alternative method:
  putUserProperty(Object key, Object value)	putUserProperty(String key, Object value)
  getUserProperty(Object key)	getUserProperty(String key)
  removeUserProperty(Object key)	removeUserProperty(String key)

The old methods will remain in all jadice® 4.2 releases. Calling those methods with a key not of type java.lang.String will result in IllegalArgumentExceptions! Since jadice® 4.3 releases these methods are removed and not available anymore.

Replaced classes and interfaces

• The following classes are replaced or renamed for refactoring reasons. In the majority of cases these classes keep fully their functionality, mostly their API was extended. The table shows the old and the new class signatures.

  Class 3.x:	Class 4.3.x:
  com.levigo.jadice.gui.ProductInformation	com.levigo.jadice.prodinfo.ProductInformation
  com.levigo.jadice.commands.AbstractDocumentCommand	com.levigo.jadice.docs.AbstractDocumentCommand
  com.levigo.jadice.commands.DocumentCommands Example: com.levigo.jadice.commands.DocumentCommands.ToggleHoverLens	Document specific functionalities: com.levigo.jadice.docs.DocumentCommands AddOn specific functionalities replaced by addOn specific commands. com.levigo.jadice.addon.lens.ToggleHoverLensCommand
  com.levigo.jadice.commands.AbstractViewerCommand	com.levigo.jadice.AbstractViewerCommand
  com.levigo.jadice.docs.resource.DefaultResourceLoader	com.levigo.jadice.formats.modca.DefaultResourceLoader
  com.levigo.util.log.LogAdapter	Removed. See com.levigo.jadice.util.DefaultLogger in "Semantical replacements" below.

Semantical replacements

• The following table presents semantical changes.

  Class 3.x:	Changed in 4.3.x:
  com.levigo.jadice.docs.RenderingHint and subclasses	Replaced by com.levigo.jadice.docs.ProcessingSettings and subclasses
  com.levigo.jadice.util.DefaultLogger	Removed. Not used and not required anymore. Replaced by the settings of the logging system the jadice xAE logging framwork face delegates to. See therefore the jadice xAE logging framework facade.

Action and command configuration files

To complete the migration process keep in mind to adapt the configuration files of the action and commands framework, too.

To migrate own configurations take into account that the configuration files contain references on concrete command realizations as well as references on corresponding configurations. All of these references must be adapted accordingly.

If there are no own configuration files, but customized copies the jadice configuration files placed in the classpath before of the jadice document platform modules, there are two possible ways to migrate these configurations.

If there is just a limited number of customizing changes performed on the copies of the jadice configuration files, just copy the new 4.3 configuration files, repeat the customizing changes on these files and replace the older configuration files with these new copied and customized ones.

If the number of changes of customized configuration copies is too large or too complex to be repeated, the configuration have to be migrated manually. Therefore examine thoroughly all referenced commands.properties configurations, check each command realization reference (classpath and classname) and replace it with the newer class reference if necessary. For this purpose this documentation can be useful. The new configuration files distributed within the 4.3 release should be considered, too. Bear in mind that some old commands with very similar functionality are summarized in the new 4.3 version to new parameterizable commands. For more information of these commands refer to the javadoc and the descriptions in the new command properties files.

Keep in mind that the configuration files are provided in internationalized variants. In order to avoid inconsistencies configuration changes should always be done in all variants, at least, however, in the variant corresponding to the current locale.