Changes between Initial Version and Version 1 of OldRDF2JavaUsingDFKIKnowledgeBase


Ignore:
Timestamp:
09/22/05 17:00:34 (14 years ago)
Author:
kiesel
Comment:

moved away old docs (rdf2java is Jena-based now)

Legend:

Unmodified
Added
Removed
Modified
  • OldRDF2JavaUsingDFKIKnowledgeBase

    v1 v1  
     1== 1. Introduction == 
     2 
     3rdf2java is a small tool written in Java. It allows easy handling of RDF data. Instead of using an RDF api for creating and searching for RDF triples, i.e., (subject, predicate, object), you just work with Java objects representing RDF subjects / objects. 
     4 
     5Typically, you first create an RDFS (RDF Schema) file, containing declarations for classes and properties. RDF data (e.g. in an RDF file) refers to this RDFS file, just like an XML file can refer to a DTD or to an XML Schema file. The RDF Schema specifies what kind of RDF subjects (i.e. instances of these classes) are allowed and how they are linked to each other (-> properties). 
     6So, you have RDFS specifications and RDF data (instances) matching this RDF Schema. 
     7 
     8Using rdf2java (or, to be more precise, the rdfs2class utility of the rdf2java package), we first create Java classes corresponding to the RDFS classes. Then we can use rdf2java to "read in" RDF data, and convert them to Java objects, being instances of the respective Java classes. 
     9 
     10The original tool was written by Michael Sintek. Information and download of the old tool can be found [http://www.dfki.uni-kl.de/frodo/rdf2java/ here]. 
     11I developed his tool further to suit our increasing needs in the [http://www.dfki.uni-kl.de/frodo/ FRODO] project. 
     12 
     13== 1.1  Example: == 
     14 
     15Consider the following RDFS file (XML syntax) declaring a class Person having two properties: (1) name is a string-valued property (->Literal) and (2) hasParent demands a reference to another instance of Person. 
     16[I won't go into detail wrt. RDFS and its typical XML syntax; see http://www.w3.org/TR/rdf-schema/ for more information on this topic.] 
     17 
     18{{{ 
     19<?xml version='1.0' encoding='ISO-8859-1'?> 
     20<!DOCTYPE rdf:RDF [ 
     21     <!ENTITY rdf 'http://www.w3.org/1999/02/22-rdf-syntax-ns#'> 
     22     <!ENTITY rdfs 'http://www.w3.org/TR/1999/PR-rdf-schema-19990303#'> 
     23     <!ENTITY example1 'http://org.dfki/rdf2java/example1#'> 
     24]> 
     25 
     26<rdf:RDF  
     27     xmlns:rdf="&rdf;" 
     28     xmlns:rdfs="&rdfs;" 
     29     xmlns:example1="&example1;"> 
     30 
     31<rdfs:Class rdf:about="&example1;Person"> 
     32    <rdfs:subClassOf rdf:resource="&rdfs;Resource"/> 
     33</rdfs:Class> 
     34 
     35<rdf:Property rdf:about="&example1;hasParent"> 
     36    <rdfs:range rdf:resource="&example1;Person"/> 
     37    <rdfs:domain rdf:resource="&example1;Person"/> 
     38</rdf:Property> 
     39 
     40<rdf:Property rdf:about="&example1;name"> 
     41    <rdfs:domain rdf:resource="&example1;Person"/> 
     42    <rdfs:range rdf:resource="&rdfs;Literal"/> 
     43</rdf:Property> 
     44 
     45</rdf:RDF> 
     46}}} 
     47 
     48Just to give you an idea, here's the plain set of RDF triples (subject, predicate, object) for the RDF Schema above. You may need to use your scroll bar! I sorted the triples for your convenience; don't forget, they aren't, really: 
     49 
     50{{{ 
     51http://org.dfki/rdf2java/example1#Person    , http://www.w3.org/1999/02/22-rdf-syntax-ns#type             , http://www.w3.org/TR/1999/PR-rdf-schema-19990303#Class 
     52http://org.dfki/rdf2java/example1#Person    , http://www.w3.org/TR/1999/PR-rdf-schema-19990303#subClassOf , http://www.w3.org/TR/1999/PR-rdf-schema-19990303#Resource 
     53http://org.dfki/rdf2java/example1#hasParent , http://www.w3.org/1999/02/22-rdf-syntax-ns#type             , http://www.w3.org/1999/02/22-rdf-syntax-ns#Property 
     54http://org.dfki/rdf2java/example1#hasParent , http://www.w3.org/TR/1999/PR-rdf-schema-19990303#domain     , http://org.dfki/rdf2java/example1#Person 
     55http://org.dfki/rdf2java/example1#hasParent , http://www.w3.org/TR/1999/PR-rdf-schema-19990303#range      , http://org.dfki/rdf2java/example1#Person 
     56http://org.dfki/rdf2java/example1#name      , http://www.w3.org/1999/02/22-rdf-syntax-ns#type             , http://www.w3.org/1999/02/22-rdf-syntax-ns#Property 
     57http://org.dfki/rdf2java/example1#name      , http://www.w3.org/TR/1999/PR-rdf-schema-19990303#domain     , http://org.dfki/rdf2java/example1#Person 
     58http://org.dfki/rdf2java/example1#name      , http://www.w3.org/TR/1999/PR-rdf-schema-19990303#range      , http://www.w3.org/TR/1999/PR-rdf-schema-19990303#Literal 
     59}}} 
     60 
     61Assume, there is an RDF file containing some instances of this RDFS class (Person): 
     62 
     63{{{ 
     64<?xml version='1.0' encoding='ISO-8859-1'?> 
     65<!DOCTYPE rdf:RDF [ 
     66     <!ENTITY rdf 'http://www.w3.org/1999/02/22-rdf-syntax-ns#'> 
     67     <!ENTITY rdfs 'http://www.w3.org/TR/1999/PR-rdf-schema-19990303#'> 
     68     <!ENTITY example1 'http://org.dfki/rdf2java/example1#'> 
     69]> 
     70 
     71<rdf:RDF  
     72     xmlns:rdf="&rdf;" 
     73     xmlns:rdfs="&rdfs;" 
     74     xmlns:example1="&example1;"> 
     75 
     76<example1:Person rdf:about="&example1;example1_00005" 
     77     example1:name="Bart Simpson"> 
     78    <example1:hasParent rdf:resource="&example1;example1_00006"/> 
     79</example1:Person> 
     80 
     81<example1:Person rdf:about="&example1;example1_00006" 
     82     example1:name="Homer Simpson"/> 
     83 
     84</rdf:RDF> 
     85}}} 
     86 
     87Again, just to give you an idea of the plain RDF, here are the triples, again ordered for your convenience (you may need to use your scroll bar): 
     88 
     89{{{ 
     90http://org.dfki/rdf2java/example1#example1_00005 , http://www.w3.org/1999/02/22-rdf-syntax-ns#type , http://org.dfki/rdf2java/example1#Person 
     91http://org.dfki/rdf2java/example1#example1_00005 , http://org.dfki/rdf2java/example1#hasParent     , http://org.dfki/rdf2java/example1#example1_00006 
     92http://org.dfki/rdf2java/example1#example1_00005 , http://org.dfki/rdf2java/example1#name          , Bart Simpson 
     93http://org.dfki/rdf2java/example1#example1_00006 , http://www.w3.org/1999/02/22-rdf-syntax-ns#type , http://org.dfki/rdf2java/example1#Person 
     94http://org.dfki/rdf2java/example1#example1_00006 , http://org.dfki/rdf2java/example1#name          , Homer Simpson 
     95}}} 
     96 
     97When you visualize these set of triples you receive the following picture (only the RDF data is shown, not the RDF Schema). Boxes represent resources (RDF subjects) whereas ellipses show literals (strings), which can only be RDF objects. The named and directed edges visualize the predicates. 
     98 
     99http://www.dfki.uni-kl.de/~schwarz/rdf2java/testdata/example/example1.a.75.gif 
     100[[BR]] ''graph representation of these RDF triples'' 
     101 
     102This RDF data contains two Persons: Bart Simpson and Homer Simson, whereas Bart has a parent, namely Homer. 
     103 
     104Now, assume further, there is a Java class named Person, having the following structure: 
     105 
     106{{{ 
     107public class Person 
     108{ 
     109    public void putName(String name) {...} 
     110    public String getName() {...} 
     111 
     112    public void putHasParent(Person parent) {...} 
     113    public Person getHasParent() {...} 
     114} 
     115}}} 
     116 
     117The classes may get more complicated later, and the implementation is still missing, but for the moment that should do to get the picture... Besides the structure (the public getters and putters) are more important than the concrete implementation. 
     118 
     119Using RDF Import (rdf2java API), you can transform the RDF data above into two Java objects, i.e., instances of the class Person. These instances will be created using Java's reflection API, so, they are created during run-time. After creation, both will be initialized calling the public method putName, and for one of them the method putHasParent will be called, too. This will result in two Java objects, one for "Bart" and one for "Homer". Additionally, the Bart-object links to the Homer-object. 
     120 
     121There is of course a bit more salt in the objects, e.g., Person does really extend from a class called THING, which in turn extends from a class called RDFResource, but this will be handled later. Just to give you a hint: RDFResource provides getters and putters for the object's URI (unified resource identifier). Hence, calling the method getURI on the Bart-object, you receive http://org.dfki/rdf2java/example1#example1_00005, whereas when you call getURI on the Homer-object, you get http://org.dfki/rdf2java/example1#example1_00006. See the RDF file above to make yourself clear why. 
     122 
     123What you don't see in the example is, that classes can be sub-classes of another class. As RDFS doesn't provide multiple inheritance, rdf2java doesn't support multiple inheritance either. This remark is for people using Protégé-2000 (see below) to generate and work on RDF/S. 
     124 
     125== 1.2  What rdf2java can do == 
     126 
     127Opposed to plain RDF, rdf2java distinguishes between, you could say, "near" and "remote" objects. The reason is as follows: RDF data is just a set of triples (subject, predicate, object), which means, that links to objects are always represented by a triple (object, relation, other-object). As soon as this triple exists, the relation exists, no matter whether the linked resource exists or not, the reference to that resource always does. 
     128 
     129On the Java-side, this is different. Keeping in mind the simple structure of the class Person above, the referenced Java object must be available, to establish the relation. For example, If the Homer-object is not available (there is no no Java-pointer available),  you can not reference the Homer-object, and hence, you can not establish a link (relation) between the two, although there might be such a Homer-object "living" on some other computer or in some other Java-VM (Java virtual machine). 
     130 
     131Therefore, rdf2java distinguishes between the two cases: (1) An object is either available in the current Java-VM, then it is an instance of THING; (2) The object is not available in the current Java-VM, then it is represented by an RDFResource, providing at least the URI of the referenced object. 
     132A THING is an RDFResource, which means, that also THINGS know about their URIs. 
     133 
     134== 1.3  What rdf2java can not do == 
     135 
     136We are using Java objects as representatives for RDF subjects / objects. As such a Java object is an instance of some Java class, Java binds the object's Java pointer forever to this object, and furthermore to its class. Hence, the class of a Java object can never change, which means, that the represented RDF subject can never change it's belonging to a class. But this is different from the plain RDF world, where this is possible. 
     137However, when you know, that an RDF subject will never change it's class, you won't have any problems using rdf2java. 
     138 
     139== 1.4  rdf2java works well with RDFS produced by Protégé-2000 == 
     140RDFS unfortunately lacks some property constraints, such as, specifying whether a property can only contain a single value (only one triple with that predicate allowed), or whether there can be multiple values for that property. 
     141 
     142We are using Protégé-2000 to create our Models / Meta-Models and file out the result as RDF/S. 
     143Protégé-2000 provides some interesing class and property declarations, that we don't want to miss when using rdf2java later on. Therefore rdf2java interpretes some of the Protégé-2000 specific declarations. 
     144 
     145RDF files exported via rdf2java's RDF Export funtionality (Java objects --> RDF data) can, of course, be read in by Protégé-2000. 
     146 
     147Note: rdf2java does not support multiple inheritance (because Java doesn't either). 
     148 
     149If you like, look at some files in the example directory. However, the RDF/S files found there are slightly different than the one's I pasted above. That's because they have been generated using Protégé-2000 and, hence, they contain additional, Protégé-2000 specific modeling. If you have installed Protégé-2000, you can as well open the protege file (example1.pprj) there containing the modeling of the Person class, as well as, the modeling of the two instances for Bart and Homer. 
     150 
     151== 1.5  Online documentation (javadoc) of the rdf2java API == 
     152. . . can be found [http://www.dfki.uni-kl.de/~schwarz/rdf2java/apidoc/index.html here]. 
     153 
     154== 2. Installation == 
     155rdf2java is a pure java tool, written using Java 2, JDK 1.3.1_02. Hence, I propose to NOT use an older JDK. However, the sources are included, whereas you could try to recompile the tool with whatever JDK you like. If you are using JBuilder 6 (or later), you will even find a project file "rdf2java.jpx", so you can open it directly into the JBuilder IDE and compile it, debug it, whatever... 
     156 
     157Just download [http://www.dfki.uni-kl.de/~schwarz/rdf2java.zip rdf2java.zip] and extract it to some directory, e.g., C:\java\  (an rdf2java directory will be created there automatically).<br/> 
     158However: This ZIP can be quite old, contact the developers (see link at the top of the page) for a newer one. 
     159The reason for this is, that as are using subversion for development, the ZIP is not created automatically. Sorry for that inconvenience! 
     160 
     161Top-level directories:[[BR]] 
     162doc      : documentation (javadoc)[[BR]] 
     163import   : jar-files needed by rdf2java; these must be included in the CLASSPATH ("java -cp ..."), when using rdf2java.[[BR]] 
     164lib      : jar-file of the rdf2java tool; of course this must be included in the CLASSPATH, as well.[[BR]] 
     165src      : the complete source code[[BR]] 
     166testdata : some test data for examples[[BR]] 
     167 
     168All you need to use rdf2java is to get the CLASSPATH right, whenever starting a Java-VM. You can either set the CLASSPATH environment variable, or specify the classpath temporarily via the "-cp" parameter whenever you call the java interpreter. 
     169 
     170lib/rdf2javaApidoc.jar contains the API documentation (javadoc) in a jar-file. It is much more compact that way and could such be stored better in our CVS repository. 
     171 
     172All tools and elements included in rdf2java are in the package dfki.rdf.util. 
     173 
     174== 3. Create the Java files from a RDFS file == 
     175 
     176If you want to use RDF Import / Export functionality for some RDF data, you need a set of Java classes which correspond exactly to the RDF data, which means, that there must be a Java class for each RDF class instantiated in the RDF data. Furthermore, all relations between RDF subjects / objects must correspond to getter and putter methods in the Java classes. 
     177For example, if there is a triple (a, b, c) in the RDF data (meaning a --b--> c), the Java object for a must provide the methods getB and putB. 
     178 
     179== 3.1  RDFS2Class (dfki.rdf.util.RDFS2Class) == 
     180 
     181If there's an RDFS file available specifying the allowed classes and properties (i.e. relations), you can let rdf2java create the needed corresponding Java classes for you. The tool RDFS2Class, which is part of rdf2java, will generate the source code for theses classes out of a given RDFS file. 
     182 
     183Look up the batch-file testdata/assign/rdfs2class.bat for an example of how to call the RDFS2Class tool. 
     184 
     185Generally, you will have to call RDFS2Class as follows: 
     186 
     187{{{ 
     188java -cp <...CLASSPATH...> dfki.rdf.util.RDFS2Class <...FLAGS...> 
     189                                                    <...RDFS-FILE...> 
     190                                                    <...OUTPUT-SRC-DIR...> 
     191                                                    <...N1...>   <...P1...> 
     192                                                    <...N2...>   <...P2...> 
     193                                                    <...N3...>   <...P3...> 
     194                                                             . . . 
     195}}} 
     196 
     197whereas 
     198 
     199{{{ 
     200FLAGS:    -q: quiet operation, no output 
     201          -s: include toString()-stuff in generated java-files 
     202          -S: include recursive toString()-stuff in generated java-files 
     203              (used instead of -s) 
     204          -o: retain ordering of triples (usage of rdf:Seq in rdf-file) 
     205              by using arrays instead of sets 
     206          -I: insert stuff for incremental file-generation 
     207              (needed for potential later usage of -i) 
     208              ATTENTION: this option completely re-creates java-files and 
     209              erases every user-defined methods and slots,  
     210              maybe you'd better use "-i" ?! 
     211          -i: incremental generation of java-files, i.e. user added slots 
     212              are kept in the re-generated java-files 
     213              (this option includes already -I) 
     214          Order of the following options is important! 
     215          rdfs=<namespace>    : set different RDFS namespace 
     216          rdf=<namespace>     : set different RDF namespace 
     217          protege=<namespace> : set different Protege namespace 
     218 
     219RDFS-FILE      : the RDFS-file declaring the classes and properties 
     220 
     221OUTPUT-SRC-DIR : generated source files (not class files) go to this directory 
     222 
     223(N1, P1), ...  : pairs of namespaces and package-names; this specifies how to 
     224                 map namespaces to package-names 
     225}}} 
     226 
     227We typically use "-is" as FLAGS, which includes a toString method and allows for editing the Java classes without problems. 
     228 
     229As RDF/S normally uses namespaces to ensure uniqueness of RDF resources all over the world, rdf2java maps the needed namespaces to package-names. This means, that RDFS2Class will create the corresponding directory structure, as well. 
     230 
     231For our small example above, let's assume, you've got an appropriate RDF Schema file in C:\TEMP\example1.rdfs. Then you could call RDFS2Class with the following parameters: 
     232 
     233{{{ 
     234java -cp <...CLASSPATH...> dfki.rdf.util.RDFS2Class 
     235                           -is 
     236                           C:\TEMP\example1.rdfs 
     237                           C:\TEMP\src 
     238                           http://org.dfki/rdf2java/example1# 
     239                                  org.dfki.rdf2java.example1 
     240}}} 
     241 
     242Please note, the last two(!) parameters. We are used to mapping the namespaces to packages with nearly identical names (slashes become dots), but you are not oblighed to do that. You could even map different namespaces to just one package. However, then you could not export (RDF Export) Java objects to RDF data. 
     243 
     244For more information, please look at some files in the example directory. 
     245However, the RDF/S files found there are slightly different than the one's I pasted above. That's because they have been generated using Protégé-2000 and, hence, they contain additional, Protégé-2000 specific modeling. Also the generated Java class org.dfki.rdf2java.example1.Person is a bit more complex than the structure snipped above, but after having a look at it, you should roughly get the picture. Besides, although you can, you won't look into these classes very often. They are structures for keeping and representing some RDF data. In most cases, you will do nothing more than just call the getters and putters of these objects. 
     246 
     247== 4. RDF Import / Export (RDF data <--> Java instances) == 
     248 
     249Look at !SimpleImportExport.java to get an understanding of how the import / export works. 
     250For a better understanding I pasted an extract of the most important parts of the code below (marginal stuff like, e.g., exception handling has been removed): 
     251 
     252{{{ 
     253import dfki.rdf.util.RDFImport; 
     254import dfki.rdf.util.RDFExport; 
     255 
     256import org.dfki.rdf2java.example1.Person; 
     257 
     258public class SimpleImportExport 
     259{ 
     260    public static void main( String[] args ) 
     261    { 
     262        final String NAMESPACE_1 = "http://org.dfki/rdf2java/example1#"; 
     263        final String PACKAGE_1   = "org.dfki.rdf2java.example1"; 
     264 
     265        Map mapNamespace2Package = new HashMap(); 
     266        mapNamespace2Package.put( NAMESPACE_1, PACKAGE_1 ); 
     267        RDFImport rdfImport = new RDFImport( mapNamespace2Package ); 
     268 
     269        // 1. import from RDF file "example1.rdf" 
     270        Map mapObjects = rdfImport.importObjects( "testdata/example/example1.rdf" ); 
     271        printout( mapObjects ); 
     272 
     273        // 2. make some changes (or additions) 
     274        //    e.g. add an object for "Lisa Simpson" 
     275        final String NAMESPACE_FOR_NEW_INSTANCES = NAMESPACE_1; 
     276        Person lisa = new Person(); 
     277        lisa.makeNewURI( NAMESPACE_FOR_NEW_INSTANCES ); 
     278        lisa.putName( "Lisa Simpson" ); 
     279        // get object for "Homer"; you must know Homer's URI: "http://...#example1_00006 
     280        Person homer = (Person)mapObjects.get( "http://org.dfki/rdf2java/example1#example1_00006" ); 
     281        lisa.putHasParent( homer ); 
     282        // add lisa object to mapObjects (so she can be exported in step 3 below) 
     283        mapObjects.put( lisa.getURI(), lisa ); 
     284        System.out.println( "\n\n----------\nadded lisa\n----------\n" ); 
     285        printout( mapObjects ); 
     286 
     287        // 3. export to RDF file "example1_lisa.rdf" 
     288        Map mapPackage2Namespace = new HashMap(); 
     289        mapPackage2Namespace.put( PACKAGE_1, NAMESPACE_1 ); 
     290        RDFExport rdfExport = new RDFExport( NAMESPACE_FOR_NEW_INSTANCES, mapPackage2Namespace ); 
     291        rdfExport.exportObjects( mapObjects.values(), "testdata/example/example1_lisa.rdf" ); 
     292    } 
     293 
     294    public static void printout( Map mapObjects ) 
     295    { 
     296        for( Iterator it = mapObjects.keySet().iterator(); it.hasNext(); ) 
     297        { 
     298            String sURI = (String)it.next(); 
     299            Object obj = mapObjects.get( sURI ); 
     300            System.out.println( "\n########## " + sURI + " ##########\n" + obj ); 
     301        } 
     302    } 
     303} 
     304}}} 
     305 
     306 
     307== 5. Knowledge Base (dfki.rdf.util.KnowledgeBase) == 
     308 
     309The !KnowledgeBase class stores and maintains Java objects (representing some RDF data). At first sight, it provides hardly more than a simple data storage class.  You could as well do fine with some java.util.Collection. However, the stored Java objects shall represent RDF data, which unfortunately delivers some problems. RDF (Resource Description Framework) is designed to talk about things (resources) with the explicit intention to talk about resources far away, think of all the distributed documents (e.g. web pages) around the world. You can put statements in one document describing another document somewhere else on the planet. 
     310 
     311As already mentioned before (see 1.2  What rdf2java can do), rdf2java distinguishes between the two cases: (1) An object is either available in the current Java-VM, then it is an instance of THING; (2) The object is not available in the current Java-VM, then it is represented by an RDFResource, providing at least the URI of the referenced object. 
     312A THING is an RDFResource, which means, that also THINGS know about their URIs. 
     313 
     314When importing RDF data, you get a set of Java objects. Some of them will maintain links to others, some of  them will link to resources not available by Java objects. In the latter case, such a Java object links to an RDFResource. 
     315 
     316Now assume, you have imported some RDF data and, hence, you have some Java objects representing this RDF data. When you, later on, want to import another RDF, which has relationships to the RDF you have imported earlier, then you have to take care using all these Java objects. In plain RDF, being hardly more than a set of triples (subject, predicate, object), you just have to add more triples and you're done. In the Java world, however, you've got the distinction between THINGS and RDFResources. When you import new RDF and hence get new Java objects, you have make sure, that all RDFResources pointing to you new Java object are converted to direct Java pointers to the new Java object. 
     317But it's even worse: Assume having independently imported two RDF files, meaning you have got two different collections of Java objects. Big problems arise as soon as you try to merge these two. 
     318You may say, this problem can be avoided. But think about distributed scenarios, think about agents sending RDF data among themselfs (in our research project FRODO our agents do that). What happens very often is, that agents are sending updates of their data, being RDF data. When using Java objects representating this RDF, you come to the point, where you have to assert new RDF data to old RDF data. 
     319 
     320The !KnowledgeBase class solves this problem by providing methods for such assertions. As an assertion of an object works on an older version of the same object, these methods have been named assign instead of assert, but maybe we should change this...? 
     321 
     322Now, let's come to the semantics of this assign "operator". 
     323Assume you have got some objects {ai} in the knowledge base and want to assign {bj}. Then, first of all, this is identical to an iterative assignment of  all bj individually. The assignment  {ai} <- bj  works according to the following rules: 
     324 
     325 * 1. case: there is an ak with ak.getURI() = bj.getURI():[[BR]]This more or less means: bj is already in the knowledge base (that's ak), but, the bj assigned can contain other values and/or links.[[BR]]Therefore ak stays in the knowledge base, but all it's properties are getting updated. Assume, ak has got properties p1(ak),...,pn(ak)with values v1(ak),...,vn(ak);analogously bj has values v1(bj),...,vn(bj),then proceed for all m=1,...,n in the following way: 
     326   * case 1.a: pm is a single value slot: vm(ak) <- vm(bj), i.e., take the newer value (this may be even no value, which empties the property). 
     327   * case 1.b: pm is a multiple value slot and the values are strings (literals): just take all the values from vm(bj), because that are the new ones. 
     328   * case 1.c: pm is a multiple value slot and the values are links to resources (other objects): this is the most interesting case...[[BR]]First of all, all values in vm(ak) not contained in vm(bj) are removed. Then, for the rest of the values (i.e. values contained in both) check: 
     329     * IF both, vm(ak) and vm(bj) are THINGS, THEN assign vm(ak) <- vm(bj); this leads to a recursion, so, the assignment is a quite inefficient procedure! 
     330     * OTHERWISE just take out vm(ak) and take in vm(bj). Exactly this "take in" and "take out" has (by now) one great disadvantage: It may ruin the order of the multiple values. For normal RDF this causes no trouble, as there is no specification about the order of the triples, but as soon as one uses ordering stuff like rdf:seq, there's problems ahead! Although rdf2java supports ordering of multiple values, we aren't using this, because it's quite against the idea of RDF. If we need ordering, we model it explicitly through explicit structures. 
     331   * 2. case: there exists no such k with ak.getURI() = bj.getURI():[[BR]]This is, of course, the easiest case: As bj is just a new object, we put it into the knowledge base and we're done. 
     332 
     333After this assignment procedure, there's a second pass done, which updates values being only references (RDFResource), although a THING is now available. These RDFResource values are then converted to Java pointers pointing to the respective THING. This is done by method updateRDFResourceSlots, which is automatically called in the assign method (in the KnowledgeBase class). 
     334 
     335'''Examples''' 
     336 
     337We change the old example slightly, as the old example lacks interesting cases. Therefore, we add an a inverse property to hasParent, namely hasChild. Furthermore we have to add the inverse values for this slot, as this isn't done automatically. The result is example2.* in the example directory. 
     338 
     339Assume, our knowledge base contains Java objects corresponding to RDF data declaring Bart and Homer Simpson and their relationships to each other (properties hasParent and hasChild). The RDF graph for this is shown on the left image after this paragraph (namespaces have been abreviated). 
     340Assume further we want to assign a new object for Lisa Simpson plus relevant relationships to this knowledge base. You see the graphical representation of the RDF data to assign on the right image below. We will see below, the assignment won't lead to the result you might expect. Later we will show the correct RDF data to assign... 
     341 
     342http://www.dfki.uni-kl.de/~schwarz/rdf2java/testdata/example/example2.a.short.75.gif 
     343[[BR]] ''the knowledge base so far'' 
     344 
     345http://www.dfki.uni-kl.de/~schwarz/rdf2java/testdata/example/example2.b.short.gif 
     346[[BR]] ''RDF data to assign to the knowledge base'' 
     347 
     348When looking at these pictures, keep in mind, that they are nothing more than the graphical representation of RDF triples; boxes represent RDF resources, ellipses represent literals (strings). Via rdf2java, resources (boxes) for instances of RDFS classes are represented by corresponding Java objects in the knowledge base, and outgoing edges are stored in these Java objects and are available via getter methods. 
     349 
     350Hence, before the assignment, the knowledge base (left pictures) contains two Java objects: one for Bart (example1:example1_00005) and one for Homer (example1:example1_00006). Furthermore, both objects store the respective value for the name property. Finally the Bart object stores a link to the Homer object for the hasParent property, and the Homer object stores the inverse link for the hasChild property, respectively. Note, that there's no object for example1:Person as this is a class and no instance. 
     351 
     352Analogously, the RDF data to assign (right image above) will be represented (e.g. after RDF Import) by two objects, one for Lisa's resource plus outgoing edges (properties name and hasParent) and one for Homer's resource plus outgoing edges (property hasChild). Note, that this Homer object is neither the same object as the one in the knowledge base, nor has it identical values; That Homer object, e.g., doesn't have a value for the name property, whereas the Homer object in the knowledge base has. 
     353 
     354When assigning the RDF data (right image above), both of the two objects (Lisa and Homer) have to be assigned. The assignment will take place in two steps (see above): (1) the main assignment procedure, (2) updating all the property values linking to an RDFResource, which after the assignment is available as a THING. 
     355The first step of assigning Lisa's object is easy, as it doesn't yet exist in the knowledge base. Therefore, the object will bluntly be added (including inthere all information about outgoing edges) to the knowledge base. 
     356Assigning the Homer object, or to be more precise: the RDF data stored in the Homer object, is a bit more complicated. First of all, there exists already a Homer object in the knowledge base. Hence, the object can not be simply added, but must be assigned to the already existing one. Therefore, all Homer properties have to be examined. 
     357name: left-side Homer stores a value, right-side Homer doesn't. Possible interpretation: right-side lacks (leaves out) this information? No! Our interpretation is: the right-side Homer is the newer one and contains all new data. Hence, the value for the name property will be deleted on the left-side Homer object. 
     358hasChild: both Homer objects have different (disjoint) values for that property, so we take the new ones, i.e., the ones at the right side. 
     359The result (knowledge base) is as follows: 
     360 
     361http://www.dfki.uni-kl.de/~schwarz/rdf2java/testdata/example/example2.c.short.75.gif 
     362 
     363The result is not quite the one, you might have expected when I started this example. There are several mistakes: The Bart object forgot about his name. Then it still "knows" about his parent, but the Homer object doesn't reflect this relationship. As RDF/S doesn't know anything about inverse slots, this is this correct RDF. Finally it's not quite what we wanted to receive. The problem arose right at the beginning, where we specified, what RDF data to assign to the knowledge base. Let's make another assignment: 
     364 
     365http://www.dfki.uni-kl.de/~schwarz/rdf2java/testdata/example/example2.a.short.75.gif 
     366[[BR]] ''the knowledge base so far'' 
     367 
     368http://www.dfki.uni-kl.de/~schwarz/rdf2java/testdata/example/example2.b2.short.75.gif    
     369[[BR]] ''RDF data to assign to the knowledge base'' 
     370 
     371Note, that example1:example1_00005 (on the right image) will only be represented by an RDFResource object, because the right-side Homer object just needs to links to a reference of this resource. There's no need to know about about or change this resource. The Homer object has to be changed because of the hasChild property. Hence, we need to represent that by a THING object and add / change the property values we like. 
     372However, the result of this assignment will be as follows: 
     373 
     374http://www.dfki.uni-kl.de/~schwarz/rdf2java/testdata/example/example2.d.short.75.gif