WARNING: This server provides a static reference view of the NetKernel documentation. Links to dynamic content do not work. For the best experience we recommend you install NetKernel and view the documentation in the live system .

An endpoint is a space element that provides a gateway between logical resources and physical code. An endpoint is bound to a space through a set of identifiers that resolve to the endpoint.

At the logical level, when a request arrives at a space it is the responsibility of the space to determine if the request resolves to an endpoint within the space and to then forward the request to that endpoint. In NetKernel 4 the space delegates resolution to each endpoint by sending each endpoint a resolution request. If an endpoint responds affirmatively to the resolution request then the space send a resource request to that endpoint. (At the physical level, the kernel is the actor, playing a role similar to an operating system. At the physical level the kernel issues resolution requests and resource requests and provides the spacial context as an argument.)

From the perspective of an endpoint, it participates in the two phases of request processing:

  • Request Resolution - an endpoint may be asked to resolve a request.
  • Request Evaluation - a resolved endpoint is asked to create and return a resource representation.

There are many types of endpoints, each characterized by functionality or type of use. For example transreptors, accessors, transports and overlays are all distinct types of endpoints.

Physical Endpoint

A physical endpoint is physical level code that processes both the request resolution and request evaluation phases of request processing.

Java Class

The most common physical endpoint is a single object instantiated from a Java class. A physical endpoint is defined with the endpoint element and the class child element, specifying a Java class. When the space containing this declaration is commissioned, a single object of the specified class type is instantiated in memory and then commissioned to be made ready to process requests.

<endpoint>
  <class>com.mycomp.endpoints.MyEndpoint</class>
</endpoint>

It is the responsibility of each endpoint to answer a request resolution query (sent to the onResolve() method) which asks if the endpoint resolves the current request. The endpoint may use one or more facets of the request to determine if it resolves. The most commonly used facet is the resource identifier; other facets considered could include the request verb, the desired representation class, etc.

A grammar obviates the need to implement the onResolve() method when the sole request facet considered for resolution is the resource identifier. A grammar is a bi-directional request identifier parsing and construction technology used by physical endpoints to handle the request resolution phase. For example, the following simple grammar binds the identifier res:/tutorial/endpoint to the space and associates the specified Java class:

<endpoint>
  <grammar>res:/tutorial/endpoint</grammar>
  <class>com.mycomp.endpoints.MyEndpoint</class>
</endpoint>

Logical Endpoint

A logical endpoint is the logical level point of resolution for a set of resource requests.

The facets of resource requests that determine membership in the set associated with a logical endpoint are based on design decisions. The most common facet used to determine set membership is the resource identifier. For example, the set of requests with identifiers starting with active:md5+operand@ could be considered the set that maps to a single logical endpoint.

A single physical endpoint may implement one or more logical endpoints.

A common case is a single physical endpoint implementing a single logical endpoint. For example, a single Java class implements the logical endpoint mapping all requests for the MD5 service:

<endpoint>
  <grammar>
    <active>
      <identifier>active:md5</identifier>
      <argument name="operand" min="1" max="1" />
    </active>
  </grammar>
  <class>org.netkernel.security.MD5Accessor</class>
</endpoint>

Another common case is an overlay. An overlay is single physical endpoint that may implement all of the logical endpoints found in another space.

Standard Endpoint Metadata

Any endpoint declaration may provide system metadata:

<endpoint>
  <id />
  <description />
  <icon />
</endpoint>

  • id - is an optional endpoint identifier. This enables the endpoint itself to be identified which is useful for some architectural components or if you want to issue direct requests to endpoint. If omitted an id is auto generated.
  • description - a short text string human readable description.
  • icon the URI address of a bitmap icon.
  • meta optional freeform XML meta-data attached to endpoint