org.topoweb.ila.protocol
Class RemoteIla

java.lang.Object
  |
  +--org.topoweb.ila.protocol.RemoteService
        |
        +--org.topoweb.ila.protocol.RemoteIla

All Implemented Interfaces:

Ila, NodeConstants, ProtocolConstants

public class RemoteIla

extends RemoteService

implements Ila

Ila implementation over an XML/DOM protocol. This is a client-side interface implementation.

Author:

Babak Farhang

Field Summary

Fields inherited from interface org.topoweb.ila.NodeConstants

BACK, FIRST_PAGE, FORE, LAST_PAGE, LINK_MASK, PAGE_MASK

Fields inherited from interface org.topoweb.ila.protocol.ProtocolConstants

PC_BACKLINK_COUNT, PC_BACKLINKS, PC_CO_BACKLINK_COUNT, PC_CO_FORELINK_COUNT, PC_CONTENT_LENGTH, PC_CONTENT_TYPE, PC_ERROR_CODE, PC_EXPIRATION, PC_FAIL, PC_FIRST, PC_FORELINK_COUNT, PC_FORELINKS, PC_GET_KNOWN, PC_GET_LINK_NODE, PC_GET_LINKS, PC_GET_NODE, PC_HI, PC_HTTP, PC_ID, PC_ILA, PC_INCOMMUNICADO, PC_LAST, PC_LAST_MODIFIED, PC_LINK_NODE, PC_LINK_TYPE, PC_LO, PC_MAX_COUNT, PC_NODE, PC_NODE_SET, PC_OKAY, PC_ORI, PC_PAGE, PC_REGISTER, PC_REQUEST, PC_RESPONSE, PC_SIZE, PC_STATE, PC_STATUS, PC_SYNC_VERSION_ID, PC_SYNC_VERSION_TIMESTAMP, PC_TITLE, PC_USER, PC_USER_AGENT, PC_USER_NAMESPACE, PC_VERSION, PC_VERSION_ID, PC_VERSION_TIMESTAMP

Constructor Summary

RemoteIla(PLinkNode plinknode, PNodeSet pnodeset, PNode pnode, org.topoweb.xml.DomProtocol phandler)
Creates a new instance with the given entity translators and protocol handler.

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.

Methods inherited from class org.topoweb.ila.protocol.RemoteService

checkVersion, getAnswerElement, getVersion, newTransactionId

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RemoteIla

public RemoteIla(PLinkNode plinknode,
                 PNodeSet pnodeset,
                 PNode pnode,
                 org.topoweb.xml.DomProtocol phandler)
          throws java.lang.IllegalArgumentException

Creates a new instance with the given entity translators and protocol handler. The entity translators plinknode, pnodeset and pnode encapsulate the XML representations of LinkNode, NodeSet and Node instances, respectively. The protocol handler phandler encapsulates the network communication logic (e.g. server resolution, redirects, and so on).

Parameters:

plinknode - LinkNode protocol translator

pnodeset - NodeSet protocol translator

pnode - Node protocol translator

phandler - the protocol handler that retrieves responses

Throws:

java.lang.IllegalArgumentException - if any of the parameters is null

Method Detail

getNode

public Node getNode(org.topoweb.net.Ori src)
             throws IlaException

Description copied from interface: Ila

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.

Specified by:

getNode in interface Ila

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

Description copied from interface: Ila

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.

Specified by:

getLinks in interface Ila

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

Description copied from interface: Ila

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.

Specified by:

getLinkNode in interface Ila

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

Description copied from interface: Ila

Returns a list of nodes known by Ila in the given lexical range as a NodeSet.

Specified by:

getKnown in interface Ila

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

Description copied from interface: Ila

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.

Specified by:

register in interface Ila

Parameters:

ori - the ORI of the resource

Returns:

a link-node containing the forward links of the resource

Throws:

IlaException - if an error occurs