001    /**
002     * Instance.java
003     * jCOLIBRI2 framework. 
004     * @author Juan A. Recio-García.
005     * GAIA - Group for Artificial Intelligence Applications
006     * http://gaia.fdi.ucm.es
007     * 11/01/2007
008     */
009    package jcolibri.datatypes;
010    
011    import jcolibri.connector.TypeAdaptor;
012    import jcolibri.exception.OntologyAccessException;
013    import jcolibri.util.OntoBridgeSingleton;
014    
015    /**
016     * Represents an Instance of an ontology.<p>
017     * This class uses OntoBridge to connect with the ontology.
018     * <p>
019     * It can manage both short or long names to localize an instance:<br>
020     * For example: In the gaia.fdi.ucm.es/ontologies/Restaurant.owl ontology, the long name of the concept "wine" is 
021     * "gaia.fdi.ucm.es/ontologies/Restaurant.owl#wine. 
022     * The short name is just "wine" or "restaurant:wine" if "restaurant" is a defined prefix for that ontology.
023     * 
024     * @author Juan A. Recio-García.
025     * @version 2.0
026     * @see jcolibri.connector.TypeAdaptor
027     */
028    public class Instance implements TypeAdaptor {
029    
030            private String name;
031            private boolean useShortName = true;
032            
033            public static Instance createInstance(String instanceName, String parentConcept)
034            {
035                    try {
036                            OntoBridgeSingleton.getOntoBridge().createInstance(parentConcept, instanceName);
037                            return new Instance(instanceName);
038                    } catch (OntologyAccessException e) {
039                            org.apache.commons.logging.LogFactory.getLog(Instance.class).error(e);
040                    }
041                    return null;
042            }
043            
044            public Instance()
045            {
046            }
047            
048            /**
049             * Creates an Instance looking for the instance in the ontology with the same name.<p>
050             * The useShortName param allows using short or long names. For example:<br>
051             * In the gaia.fdi.ucm.es/ontologies/Restaurant.owl ontology, the long name of the concept "wine" is "gaia.fdi.ucm.es/ontologies/Restaurant.owl#wine. 
052             * The short name is just "wine" or "restaurant:wine" if "restaurant" is a defined prefix for that ontology.
053             * @param instance Name of the concept in the ontology
054             * @param useShortName Use long or short name
055             * @throws OntologyAccessException
056             */
057            public Instance(String instance, boolean useShortName) throws OntologyAccessException
058            {
059                    this.useShortName = useShortName; 
060                    fromString(instance);
061            }
062            
063            /**
064             * Creates an instance connected with the instance in the ontology. It uses a short name format. 
065             * @param instance Name of the concept in the ontology
066             * @throws OntologyAccessException
067             */
068            public Instance(String instance) throws OntologyAccessException
069            {
070                    fromString(instance);
071            }
072            
073            public void fromString(String content) throws OntologyAccessException {
074                    name = getCorrectRepresentation(content);
075                    if(!OntoBridgeSingleton.getOntoBridge().existsInstance(name))
076                            throw new jcolibri.exception.OntologyAccessException("Instance: "+ name +" not found in loaded ontologies. Check names or OntoBridge configuration.");
077            }
078            
079            public String toString()
080            {
081                    return getCorrectRepresentation(name);
082            }
083    
084            public boolean equals(Object o)
085            {
086                    if(!(o instanceof Instance))
087                            return false;
088                    
089                    Instance i = (Instance)o;
090                    
091                    String otherName = i.name;
092                    if(isShort(otherName))
093                            otherName = OntoBridgeSingleton.getOntoBridge().getURI(otherName);
094                            
095                    String myName = name;
096                    if(isShort(myName))
097                            myName = OntoBridgeSingleton.getOntoBridge().getURI(myName);
098                    
099                    return myName.equals(otherName);
100            }
101            
102            public int hashCode()
103            {
104                return OntoBridgeSingleton.getOntoBridge().getURI(name).hashCode();
105            }
106            
107            /**
108             * Indicates if using a long or short name.
109             * @param yesno
110             */
111            public void useShortName(boolean yesno)
112            {
113                    useShortName = yesno;
114            }
115            
116            private String getCorrectRepresentation(String n)
117            {
118                    if(useShortName)
119                    {
120                            if(!isShort(n))
121                                    return OntoBridgeSingleton.getOntoBridge().getShortName(n);
122                    }else
123                    {
124                            if(isShort(n))
125                                    return OntoBridgeSingleton.getOntoBridge().getURI(n);
126                    }
127                    return n;
128            }
129            
130            private boolean isShort(String n)
131            {
132                    return n.indexOf('#')==-1;
133            }
134    }