Entrypoint System

The NetKernel Entrypoint System is a means for modules to integrate themselves into the NetKernel application server environment. Using the entrypoint system, modules can contribute documentation, define a plug-in application, control panel item and CRON work items.

An entrypoint is a URI exported by a module. Various parts of the NetKernel application server will issue requests for entrypoints to produce certain results. For example, the CRON transport will make a request on an entrypoint URI at a specific date and time based on its schedule. A module integrates with the Entrypoint System by exporting the resource ffcpl:/entrypoints.xml. This XML document contains the defintion of each entrypoint exposed by the module and is fully described below. Requests for entrypoints are always made from outside of its module, therefore all entrypoints must be exported or they cannot be accessed.

Programatic control and use of the entrypoint system is provided by accessors in the entrypoint module.

Entrypoint Master Index

The Entrypoint System gathers information about each module's entrypoints and stores this information in a single master entrypoints index. The master index is maintained by an initialisation hook run when NetKernel boots or is restarted. This process checks to see if modules have been added, removed or changed and if so - updates the master index.

The master index can also be rebuilt on-demand. The Quick Entrypoint Index tool in the Control Panel will rebuild the master index without performing a full text reindexing. The master index and be rebuilt and all documents can be indexed for searching by using the Full Text Reindex command on the search page.

Entrypoint Information

Entrypoint Document

To integrate with the Entrypoint system, a module must export the resource ffcpl:/entrypoints.xml and provide an entrypoint document at this address. The entrypoint document is an XML document which conforms to the entrypoint RelaxNG schema. An empty document with one empty entrypoint entry follows:

The elements in the schema have the following meanings.

element
name	Name of the entrypoint which must be unique within the module.
uri	Externally accessable URI identifier for the resource.
indexable	Contains text values describing the entrypoint. These text values are included in the full-text search index. element title A short title desc A longer description keywords Useful keywords not contained in the title or description.
fullTextIndex	A flag indicating that the contents of this entrypoint are to be indexed for global full-text searching. Documentations should include this flag. Non-text entrypoints such as icons should not use this flag.
categories	Categories is a space-separated list of tags for the entrypoint. Categories are used to associate an entrypoint with dynamically generated system tools - for example documentation, control panel etc - see below for details of categories.
group	Groups is a text description of a group. This value is used to group entrypoints together - typically for visual representation of the module.
icon	An icon is a graphic which will be used to visually represent the entrypoint (such as in the control panel).

Catogories

Entries in the categories element are used by NetKernel application server system tools to determine how the entrypoint should be presented and used. Multiple category values can be specified and must be separated by spaces.

category	description
postInstallInfo	Entrypoints with post installation information shown as the last stage of the module install process by the Module Management Wizard.
app	Indicates that this is an application.
doc	Indicates that this resource is documentation and will be dynamically added to the doc system.
doc-source	Indicates that this resource is documentation and will be dynamically added to the doc system using the second generation document system.
img	Indicates that this is an image resource.
URA	Indicates that this resource is documentation for an accessor - which will dynamically register it in the URA listing.
transport	Indicates that this resource is documentation for a transport - which will dynamically register it in the transport listing.
transreptor	Indicates that this resource is documentation for a transreptor - which will dynamically register it in the transreptor listing.
fragmentor	Indicates that this resource is documentation for a fragmentor - which will dynamically register it in the fragmentor listing.
aspect	Indicates that this resource is documentation for an aspect - which will dynamically register it in the aspect listing.
controlpanel	Indicates that this entrypoint should be added to the control panel in the back-end fulcrum.
plugin	Identifies a plugin panel resource to be dynamically added to the back-end tools - see below for description of plugin panels.
chapter	Identifies a menu resource to be dynamically added to the documentation - see below for description of dynamic menus.
hidden	Do not display in the module visualization tools.
xunit	Mark this as a unit test - see xunit guide
cron	Mark this as a cron job configuration - see cron guide

Special Entrypoints

Two entrypoint names are reserved and have special meaning.

name	used by module	description
urn:postInstall	urn:org:ten60:netkernel:ext:install	Executed once the first time the system is booted or restarted.
icon	urn:org:ten60:netkernel:ext:introspect	Identifies an icon used in administration tools to identify the module.

Plugin Panels

A Plug-in panel is a full page panel displayed in the NetKernel application server user interface which appears just like the Control Panel, the Developer Tool panel and the Documentation panel. Navigational access to plug-in panels is provided in the Application Management Panel.

To integrate a plug-in panel a module must provide:

• An entrypoint describing the navigational access including a URI reference to the panel description document.
• The panel description document.
• Entrypoints for and implementations of each plug-in panel item.

An example plug-in panel entrypoint used by the Address Book application is shown below:

The element uri must return the plug-in panel description document (an XML document described below). The title and description elements are used as the title and description both on the navigation access icon as well as the main title on the plug-in panel page. The icon element references an image resource that is displayed in several places.

Panel Description Document

The plug-in panel is fully described by the plug-in panel description document. The plug-in panel description has the following structure...

element
this	Must be the entrypoint <name> of this plug-in panel (see above).
feed	URI of an RSS feed exported by the module. The RSS feed will be pulled and rendered in the plug-in's panel. The title attribute of the feed is used as the title of the rendered feed.
widget	URI of an XHTML widget to be rendered in the plug-in panel. The XHTML widget should be a <div> block.
entrypoints	A collection of entrypoint names
entrypoint	The <name> of an entrypoint to be added to the plug-in panel.

For example, the following is the plug-in description document for the Address Book application:

Chapter

A module may publish documentation which is integrated into the NetKernel application server documentation set in the Discovered Documentation panel. Each of the items on the left hand side of the Discovered Documentation panel is a chapter and is fully described by a chapter menu description document.

A module publishes a chapter with an entrypoint having the category chapter and referencing a chapter description document. For example, the Address Book application uses the following entrypoint to publish its chapter:

A chapter description document is an XML resource which uses item and menu elements. If there is only one page in a chapter, simply use a single item element. If there are multiple pages in a chapter, use a menu element and within that element include item elements or even nested menu elements. Each menu and item element must reference a documentation page in its name attribute. For example, a single item in the chapter would use a single item element:

A chapter with multiple pages would use a menu and item elements. This example also shows how to override the title used in the menu display.

Documentation menu resources (called a "chapter" entrypoint) may be exposed from a module and will be dynamically detected and integrated into the main documentation system.

Search Index

Entrypoints which identify documentation cause that documentation to be dynamically indexed when the entrypoint is first discovered by the system. The search index is located in the scratch directory of the mod-lucene module. It can be accessed at the uri ffcpl:/org/ten60/netkernel/ext_entrypoint/master/