ONodeID.java
001 /*
002  *  Copyright (c) 1995-2012, The University of Sheffield. See the file
003  *  COPYRIGHT.txt in the software or at http://gate.ac.uk/gate/COPYRIGHT.txt
004  *
005  *  This file is part of GATE (see http://gate.ac.uk/), and is free
006  *  software, licenced under the GNU Library General Public License,
007  *  Version 2, June 1991 (in the distribution as file licence.html,
008  *  and also available at http://gate.ac.uk/gate/licence.html).
009  *
010  *  $Id: ONodeID.java 17530 2014-03-04 15:57:43Z markagreenwood $
011  */
012 package gate.creole.ontology;
013 
014 /**
015  * An ONodeID represents the id of either a blank node or a resource.
016  * If the node represented by this is a blank node, name space will be
017  * blank and the resource name will be whatever internal name for the
018  * blank node the implementation uses. If the node respresented by this
019  * is a named resource, the ID will be an URI consisting of a name space
020  * and a resource name. <br>
021  * TODO: plan for URI/IRI encodings and comparion of OURIs that have non-ASCII
022  * resource names. Most likely each ORUI will remember the string it was
023  * created from and return that string for getResourceName or toString.
024  * The toDisplayString method will always generate a valid IRI, and the
025  * toASCIIString will always generate a valid URI representation.
026  * Whether these representations are stored or generated on the fly and which
027  * of these representations are used with the backend is implementation
028  * dependent.
029  *
030  @author Johann Petrak
031  */
032 public interface ONodeID extends Comparable<ONodeID> {
033   public String getNameSpace();
034   public String getResourceName();
035 
036   /**
037    * Return the node ID as the string from which the ID was originally created.
038    */
039   @Override
040   public String toString();
041   
042   /**
043    * Return the node ID as a pure ASCII string.
044    * If the node is an OURI, this will return a string that has non ASCII
045    * characters escaped according to URI escaping rules.<br>
046    * if the node is a BNodeID, this will return the same string as toString().
047    <p> 
048    * NOTE: URI encoding and translation from/to IRIs is not implemented yet!
049    */
050   public String toASCIIString();
051   
052   /**
053    * Return the node ID as a unicode string.
054    * If the node is an OURI, this will return a string that is a valid IRI.
055    * If the node is a BNodeID, this will return the same sting as toString().
056    <p>
057    * NOTE: not implemented yet!
058    */
059   public String toDisplayString();
060   
061   /**
062    * Return if this represents a blank node or a named resource.
063    * Returns true if this represents a blank node (is a BNodeID) or a named
064    * resource (is a ORUI).
065    <p>
066    * NOTE: not implemented yet!
067    */
068   public boolean isAnonymousResource();
069 
070   @Override
071   public int compareTo(ONodeID other);
072   
073   @Override
074   public boolean equals(Object other);
075   
076   @Override
077   public int hashCode();
078   
079   /**
080    * Return a representation of the node that conforms to Turtle syntax.
081    * This will return a string that conforms to TURTLE (Terse RDF Triple
082    * Language) - see http://www.w3.org/TeamSubmission/turtle/
083    <p>
084    * TODO: at the moment, this only returns either the blank node ID unchanged
085    * or the URI as returned by toString() between "<" and ">". This will have
086    * to use a proper ASCII representation of the URI or an IRI representation
087    * instead.
088    */
089   public String toTurtle();
090   
091   /**
092    * Validate if the string that was passed on as a bnode id or as an URI/IRI
093    * to the constructor of the implementing class can be converted to
094    * a blank node identifier or and URI/IRI that conforms to the implementaion.
095    <p>
096    * TODO: this is not yet implemented.
097    
098    @throws IllegalArgumentException
099    */
100   public void validate() throws IllegalArgumentException;
101 }