com.ibm.xsp.library
Interface XspLibrary

All Known Implementing Classes:

AbstractXspLibrary

public interface XspLibrary

Defines a Xsp library.

Implementations should inherit from AbstractXspLibrary and should not have any public or protected methods, so that methods added to this interface do not break the implementations. Any new methods will have a default implementation in AbstractXspLibrary.

Method Summary

int	getBaseXspLibraryVersion() Indicates the version of the XspLibrary API that this instance was designed to use.
java.lang.String[]	getDependencies() null or the list of libraries that this one depends one.
java.lang.String	getDojoVersionRequired() Indicates this XspLibrary requires the given Dojo Toolkit core version, and will not run with an earlier Dojo version.
java.lang.String[]	getFacesConfigFiles() Return the list of faces config files contained in the library.
java.lang.String	getLibraryId() Get the library id
java.lang.String	getPluginId() Get the plug-in id.
java.lang.String	getTagVersion() Usually like the library plugin version, except without the datestamp at the end.
java.lang.String[]	getXspConfigFiles() Return the list of Xsp config files contained in the library.
java.lang.Boolean	isCompareTagVersionQualifier() Indicates that comparisons of the getTagVersion() and the XPage's library tag maximum since version should compare using the text qualifier part of the version in the comparison.
boolean	isEnabled() Return true if the library is valid for the duration of this JVM.
boolean	isGlobalScope() Check if this library should be globally available to all applications at runtime.
boolean	isTagVersionUseMicroUnderscore() Indicates that, where possible, server error messages that print out the getTagVersion() value, or the maximum library tag since version of the XPage, will display "8.5.32002.qualifier" as "8.5.3_2002.qualifier", by inserting an underscore after the before the 2nd digit of the micro number.

Method Detail

isEnabled

boolean isEnabled()

Return true if the library is valid for the duration of this JVM. This implementation should not depend on the current request, but may check server-wide configuration options or for the existence of classes it depends on. If returning false, the implementation should log the reason why it is not enabled, so that admins can understand the problem when applications that depend on this library cannot resolve it.

Returns:

true by default, or false if the application is not valid in the current runtime environment.

getLibraryId

java.lang.String getLibraryId()

Get the library id

Returns:

the id that applications will use to depend on the library

getPluginId

java.lang.String getPluginId()

Get the plug-in id. This is used by the Designer plugin.xml builder to generating the design-time plug-in dependencies, used by the Java builder to compile the XPage Java files. This is not used at runtime. Only one plug-in is allowed, because only one library plug-in will added as a runtime dependency. If more than one plugin is needed to use the library, then the library should be configured to re-export its dependencies.

Returns:

the ID of the plug-in required at design-time to compile applications using controls from this plug-in.

isGlobalScope

boolean isGlobalScope()

Check if this library should be globally available to all applications at runtime. Normally a library dependency will not exist in an application at runtime unless it was configured as a dependency at design-time; the explicit dependency is required for compile-time resolving of classes in other plugins. For global libraries, the dependency is available at runtime, even when it was not explicitly listed in the design-time dependencies. Such global libraries may be useful for contributing renderers, or converter-for-class configuration, or other runtime-only artifacts, contributed to every application that is running on the server or in the Notes Client install. That is a limited use-case, as there are not many runtime-only artifacts, for example you cannot use a control from a global library without an explicit dependency on that library, because controls require the compile-time library dependency so that the generated XPage java file will compile.

Returns:

false by default, or true if this library should be available on the classpath of every application on the server, and should contribute it's faces-config.xml files to every application.

getDependencies

java.lang.String[] getDependencies()

null or the list of libraries that this one depends one. This is used to compute the load order of the libraries. Circular dependency loops will lead to problems.

Returns:

the list of libraries this library depends on

getXspConfigFiles

java.lang.String[] getXspConfigFiles()

Return the list of Xsp config files contained in the library. Those files contain the definitions for controls and other tags. The files usually will have the file Extension ".xsp-config", but it is not necessary. These files are only loaded in Designer, and used to verify that the tags in the XPages source are valid, and to generate a compiled version of the XPage (using each tag's corresponding Java class).

Returns:

the list of the xsp config files

getFacesConfigFiles

java.lang.String[] getFacesConfigFiles()

Return the list of faces config files contained in the library. Those file contains the faces definitions (renderers...).

Returns:

the list of the faces config files

getTagVersion

java.lang.String getTagVersion()

Usually like the library plugin version, except without the datestamp at the end. This is used with the xsp-config "since" element. In the first release of the library this can return null, and the xsp-config files do not need to contain any since elements. However, if subsequent releases of the library are defining new tags or new properties on those tags, then those tags should be defined with a since version, like since>2.0<, indicating that the tag was added in version 2 of the library. Once some tags are using a since version, this method should be updated to return that version, or some later version. There will be a runtime check, when the XPage is using a tag from version 2 of the library, if the library getTagVersion() does not return version 2 or later, then it is assumed that the initial version of the library is installed, and the XPage will fail with an error message explaining that version 2 of the library is needed.

Returns:

null or a version String like "1.5.3"

getDojoVersionRequired

java.lang.String getDojoVersionRequired()

Indicates this XspLibrary requires the given Dojo Toolkit core version, and will not run with an earlier Dojo version. It does not prevent running on a later library version. null indicates that the application doesn't depend on any particular dojo version. The minimum version on a server will be Dojo 1.4.1, the version on the Domino8.5.2 environment which is required for running an XPages library like this one. When an application depends on a library using a later version than the server default, that later Dojo version will be used when running the library. If an application depends on multiple libraries, the highest library required version will be used. This Dojo version constraint will only be checked on 8.5.3 or later servers (in 8.5.2 the method is not called). If this library cannot run on an 8.5.2 server, then either the plugin dependencies should depend on 8.5.2 versions of the XPages runtime, or the isEnabled() method should return false when it detects the 8.5.2 environment. This method was added to the interface in 8.5.3.

Returns:

null or a Dojo version String like "1.4.1"

isCompareTagVersionQualifier

java.lang.Boolean isCompareTagVersionQualifier()

Indicates that comparisons of the getTagVersion() and the XPage's library tag maximum since version should compare using the text qualifier part of the version in the comparison. The qualifier will not be parsed as a number - a string comparison will be used. Prior to the 9.0.0 release, in a version like "major.minor.micro.qualifier", only the "major.minor.micro" parts of the version will be used in the version comparison. This is useful in situations where the library releases are more frequent than the increments of the micron version. This feature will not work in 8.5.2 and 8.5.3 environments. This defaults to null, in which case the behavior will depend on the result of getBaseXspLibraryVersion(). Override this to return Boolean.TRUE when the qualifier should be used.

Returns:

getBaseXspLibraryVersion

int getBaseXspLibraryVersion()

Indicates the version of the XspLibrary API that this instance was designed to use. Used in determining the default behaviors of this XspLibrary. At present (9.0.0) the only behavior depending on this option is isCompareTagVersionQualifier(). When that method returns null and this version is 3 or greater, then the behavior will be the same as Boolean.TRUE, else for 2 or earlier, the behavior will be the same as Boolean.FALSE.

0 - unknown base version.
1 - as released in Notes/Domino 8.5.2
2 - extra method getDojoVersionRequired() (added in 8.5.3)
3 - extra methods isCompareTagVersionQualifier(), getBaseXspLibraryVersion(), isTagVersionUseMicroUnderscore() (added in 9.0.0).

This method was added to the interface in 9.0.0. It defaults to 0.

Returns:

isTagVersionUseMicroUnderscore

boolean isTagVersionUseMicroUnderscore()

Indicates that, where possible, server error messages that print out the getTagVersion() value, or the maximum library tag since version of the XPage, will display "8.5.32002.qualifier" as "8.5.3_2002.qualifier", by inserting an underscore after the before the 2nd digit of the micro number. That may be useful in situations where the library must run in a pre-9.0.0 environment, so isCompareTagVersionQualifier() will not be honored, and the library releases are more frequent than the increments of the first digit of the micro version. This method was added to the interface in 9.0.0. It defaults to null (false).