Ila

org.topoweb.ila
Interface Ila

All Superinterfaces:
NodeConstants
All Known Subinterfaces:
LocalIla
All Known Implementing Classes:
IlaImpl, RemoteIla

public interface Ila
extends NodeConstants

The query interface for Ila. Implementations are usually over a network protocol.

This is a minimal implementation interface. We'll introduce convenience wrappers around it later.

Author:
Babak Farhang

Field Summary
 
Fields inherited from interface org.topoweb.ila.NodeConstants
BACK, FIRST_PAGE, FORE, LAST_PAGE, LINK_MASK, PAGE_MASK
 
Method Summary
 NodeSet getKnown(org.topoweb.util.StringRange range, int pageOrder, int maxCount)
          Returns a list of nodes known by Ila in the given lexical range as a NodeSet.
 LinkNode getLinkNode(org.topoweb.net.Ori src, int linkType, org.topoweb.util.StringRange linkRange, int pageOrder, int maxCount)
          Returns a linked-node containing links with the specified type and in the specified lexical range.
 NodeSet getLinks(org.topoweb.net.Ori src, int linkType, org.topoweb.util.StringRange linkRange, int pageOrder, int maxCount)
          Returns the links of the specified type for the node with the given Ori as a NodeSet.
 Node getNode(org.topoweb.net.Ori src)
          Returns the node for the specified Ori.
 LinkNode register(org.topoweb.net.Ori ori)
          Registers the given resource.
 

Method Detail

getNode

public Node getNode(org.topoweb.net.Ori src)
             throws IlaException
Returns the node for the specified Ori. The returned node encapsulates Ila's state of knowledge about the resource represented by the given ORI. That is, getNode(src, ..).getOri().equals(src) must evaluate to true.

Parameters:
src - the ORI of the resource
Returns:
the node representing the resource as known by Ila. Never null.
Throws:
IlaException - if an error occurs

getLinks

public NodeSet getLinks(org.topoweb.net.Ori src,
                        int linkType,
                        org.topoweb.util.StringRange linkRange,
                        int pageOrder,
                        int maxCount)
                 throws IlaException
Returns the links of the specified type for the node with the given Ori as a NodeSet.

The type of links returned, forelinks or backlinks, is determined by bitwise ORing the linkType parameter with NodeConstants mask.

The lexical range of the links to be returned is determined by the linkRange parameter.

Some nodes can have very many links, and it may be infeasible for an Ila server to return all the links that match a given request. In such an event the returned links will either start from the linkRange's lower bound if (pageOrder & PAGE_MASK ) == FIRST_PAGE, or end at its upper bound, otherwise. The user can detect whether the returned links were truncated by examining the returned NodeSet.

Note

The state information of the returned links is seldom authoritative. In fact, if the links are of the forward type (FORE) and they were just added, then it is likely they will be returned in the NK state. For any given linked node, authoritative state information is retrieved using the getNode method.

Parameters:
src - the Ori of the return linked-node
linkType - specifies whether the returned node set contains forelinks or backlinks
linkRange - the lexical range of the links returned
pageOrder - specifies whether if truncated, the links should begin from the first page or end on the last page of the link result set
maxCount - the maximum number of links that may be returned; a value <= 0 indicates an unlimited number
Returns:
a node set encapsulating the Ila server's response
Throws:
IlaException - if an error occurs
See Also:
NodeConstants, NodeConstants.FIRST_PAGE, NodeConstants.LAST_PAGE

getLinkNode

public LinkNode getLinkNode(org.topoweb.net.Ori src,
                            int linkType,
                            org.topoweb.util.StringRange linkRange,
                            int pageOrder,
                            int maxCount)
                     throws IlaException
Returns a linked-node containing links with the specified type and in the specified lexical range. The returned node represents Ila's state of knowledge about the resource represented by the given ORI src. That is, the expression
getLinkNode(src, ..).getOri().equals(src)
must evaluate to true.

This method is equivalent to invoking getNode followed by getLinks. That is, for example,

new LinkNode(src, getNode(src).getState(), null, getLinks(src, BACK, StringRange.ALL, FIRST_PAGE, 0) );
Example usage:
      Ila ila = .. ;
      LinkNode node
      = ila.getLinkNode(
      srcOri, NodeConstants.BACK, StringRange.ALL, FIRST_PAGE, 100);
      ..
 

The goal here is not a convenience method. Rather, we expect if implemented over the wire, the returned LinkNode will be marshalled in one pass, not two.

Parameters:
src - the ORI of the return linked-node
linkType - specifies whether the returned linked-node contains forelinks or backlinks
linkRange - the lexical range of the links returned
pageOrder - specifies whether if truncated, the links should begin from the first page or end
maxCount - the maximum number of links that may be returned; a value <= 0 indicates an unlimited number
Returns:
a linked-node encapsulating the Ila server's response
Throws:
IlaException - if an error occurs
See Also:
NodeConstants, NodeConstants.FIRST_PAGE, NodeConstants.LAST_PAGE

getKnown

public NodeSet getKnown(org.topoweb.util.StringRange range,
                        int pageOrder,
                        int maxCount)
                 throws IlaException
Returns a list of nodes known by Ila in the given lexical range as a NodeSet.

Parameters:
range - the lexical range of the ORIs of the nodes to be returned
pageOrder - the page order
maxCount - the maximum number of links that may be returned; a value <= 0 indicates an unlimited number
Returns:
a perhaps truncated list of nodes
Throws:
IlaException - if an error occurs
See Also:
NodeConstants.FIRST_PAGE, NodeConstants.LAST_PAGE

register

public LinkNode register(org.topoweb.net.Ori ori)
                  throws IlaException
Registers the given resource. This is the method by which a user adds information about a resource to the Ila information space. Registration entails retrieving the document at the given ori, retrieving its links, and adding that information into the Ila distributed database.

An implementation may postpone registration until the server is less busy. In such an event, the LinkNode returned will be in the NK state.

Parameters:
ori - the ORI of the resource
Returns:
a link-node containing the forward links of the resource
Throws:
IlaException - if an error occurs

Ila

Copyright (C) 2002 Babak Farhang

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.