IDocumentHandler.Priority Class

com.bea.ide.document
IDocumentHandler.Priority Class

public static class IDocumentHandler.Priority

    extends Object

This class provides a ranking mechanism to allow multiple handlers to negotiate for precedence in opening documents. One major task a document handler has is to identify the documents that it understands. Since multiple document handlers may understand the same file, this interface provides a way to rank the level of understanding so th at the document service can provide the "best" handler for a given document. The ranking mechanism is called Priority.

Each priority value represents the level of understanding of the file. It is primarily used simply to order the handlers. More general handlers should usually have lower priorities so that more specific handlers can override them by providing a higher priority value.

While priority may be declared in the extension XML, it is often the case that a handler needs to examine the contents of the file in order to determine what priority it should be. In this case the priority in the XML should be declared as "unknown". The document service will allow each "unknown" level handler to examine the file and return it's true level.

In the event that multiple handlers return the same priority value, the first such handler found will be invoked. Since there is no ordering to handlers, "the first" is not a very precise definition. Care should therefore be taken to insure that new handlers use as yet unused priority levels for a particular document. If there is sufficient need, the set of handler priority levels can easily be increased to accomodate more values.

Because two handlers of the same level are a tie, if one or more handlers statically registers in the XML as "highest", the "unknown" handlers will not be invoked to examine the contents.

One final note on priority resolution. Static xml registration allows a file-extension pattern of "*" meaning any file-extension. However, handlers that register for all file-extensions will only be allowed to resolve a handler if there are no handlers registered (of any level!) that have registered with the specific file extension.

For example, a text handler might register as "low" for all file-extensions (not recommended since it is so general). However, if another handler registers as the handler for the .xml extension, it will always get .xml files, even if it's priority is lower than "low".


Hierarchy
Object
  IDocumentHandler.Priority
Enclosing interface

IDocumentHandler

Field Summary

public static int
HIGH
int
public static int
HIGHEST
This level trumps all others.
public static int
IGNORE
This value is used to indicate that a handler does not understand the file and should not be used to open it.
public static int
INFO_ONLY
This value is typically used to indicate only that display information (icon, description, etc...) is available.
public static int
LOW
int
public static int
LOWEST
This is the first priority level that indicates the handler may be used to open the document.
public static int
MEDIUM
int
public static int
UNKNOWN
Unknown is used only in the static XML file to indicate that the runtime code must make the decision.
 

Constructor Summary

IDocumentHandler.Priority()

 

Method Summary

 
Methods from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
   

Field Detail

HIGH

public static int HIGH


HIGHEST

public static int HIGHEST
This level trumps all others. If any handlers are found with priority highest, UNKNOWN handlers will not be called. The first handler in the list (order is not deterministic) will be returned.


IGNORE

public static int IGNORE
This value is used to indicate that a handler does not understand the file and should not be used to open it.


INFO_ONLY

public static int INFO_ONLY
This value is typically used to indicate only that display information (icon, description, etc...) is available. The handler should not be used to open the file (typically this is used in the xml with no handler specified to simply provide static information about a file type).


LOW

public static int LOW


LOWEST

public static int LOWEST
This is the first priority level that indicates the handler may be used to open the document. It should typically be used by very general mechanisms like text editors or general language editors.


MEDIUM

public static int MEDIUM


UNKNOWN

public static int UNKNOWN
Unknown is used only in the static XML file to indicate that the runtime code must make the decision. It implies that priority cannot be determined statically based on the filename. This value should NEVER be returned from the IDocumentHandler.resolveUnknownPriority(IDocumentHandler.IHandlerContext) method and is considered an error.

 

Constructor Detail

IDocumentHandler.Priority

public IDocumentHandler.Priority()