Difference between revisions of "Tutorial: Quickstart"

From Developer Documents
Jump to navigation Jump to search
m
 
(17 intermediate revisions by 2 users not shown)
Line 3: Line 3:
 
=== Client opens a database session ===
 
=== Client opens a database session ===
  
To open a client session to a Simantics database server you need to fetch a [[svn:db/trunk/org.simantics.db/src/org/simantics/db/Driver.java|''Driver'']] ([http://www.simantics.org/hudson/job/javadoc/javadoc/org/simantics/db/Driver.html javadoc]) from the [[svn:db/trunk/org.simantics.db/src/org/simantics/db/Manager.java|''Driver manager'']] ([http://www.simantics.org/hudson/job/javadoc/javadoc/org/simantics/db/Manager.html javadoc]).
+
To open a client session to a Simantics database server you need to fetch a [[svn:db/trunk/org.simantics.db/src/org/simantics/db/Driver.java|''Driver'']] ([[javadoc:simantics-head/org/simantics/db/Driver.html|javadoc]]) from the [[svn:db/trunk/org.simantics.db/src/org/simantics/db/Manager.java|''Driver manager'']] ([[javadoc:simantics-head/org/simantics/db/Manager.html|javadoc]]).
  
 
The basic idea is much the same as in [http://java.sun.com/javase/technologies/database/ JDBC] [http://java.sun.com/javase/6/docs/api/java/sql/Driver.html Driver] and [http://java.sun.com/javase/6/docs/api/java/sql/DriverManager.html DriverManager].
 
The basic idea is much the same as in [http://java.sun.com/javase/technologies/database/ JDBC] [http://java.sun.com/javase/6/docs/api/java/sql/Driver.html Driver] and [http://java.sun.com/javase/6/docs/api/java/sql/DriverManager.html DriverManager].
  
 
<syntaxhighlight lang="java">
 
<syntaxhighlight lang="java">
 +
import org.simantics.db.Manager;
 +
import org.simantics.db.ServerAddress;
 +
import org.simantics.db.Session;
 +
 
     // Try to load and register the Driver instance with the driver manager
 
     // Try to load and register the Driver instance with the driver manager
 
     Class.forName("fi.vtt.simantics.procore.ProCoreDriver");
 
     Class.forName("fi.vtt.simantics.procore.ProCoreDriver");
  
 
     // Connect to the server at the specified host and credentials.
 
     // Connect to the server at the specified host and credentials.
     Session session = Manager.getSession("procore", InetSocketAddress.createUnresolved("localhost", port), username, password);
+
     Session session = Manager.getSession("procore", new ServerAddress("localhost", port), username, password);
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 42: Line 46:
  
 
         // Give the library a name
 
         // Give the library a name
         graph.claimValue(library, b.HasName, "New Library");
+
         graph.claimLiteral(library, b.HasName, "New Library");
  
 
         // Attach the library to the specified container
 
         // Attach the library to the specified container
Line 62: Line 66:
 
     }
 
     }
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
 +
=== Class Diagrams ===
 +
[[File:db1.png|thumb|center|600px|[[File:db1.graphml]]<br/><br/>Database session-level class hierarchy. Use these to manage the session and initiate read and write requests (transactions). Requests can be initiated either synchronously or asynchronously. Synchronous invocations will not return before the request has completed/failed while asynchronous requests will return immediately and completion/failure will be notified through a separate '''Procedure'''.]]
 +
 +
[[File:db2.png|thumb|center|600px|[[File:db2.graphml]]<br/><br/>Classes related to accessing the graph database during read and write transactions. ''ReadGraph'', ''AsyncReadGraph'', ''WriteGraph'' and ''WriteOnlyGraph'' are the only way to access the actual statements and values in the database. ''ReadGraph'' is a good place to get started.]]
 +
 +
[[File:db3.png|thumb|center|600px|[[File:db3.graphml]]<br/><br/>This image shows all the different kinds of requests that can be performed through ''RequestProcessor'' and ''AsyncRequestProcessor''. Beginners should focus on interfaces '''Read<T>''' and '''Write'''. Note that these request classes have default implementations that should be extended instead of directly implementing the interfaces. See the classes for more info.]]
 +
 +
[[File:db4.png|thumb|center|600px|[[File:db4.graphml]]<br/><br/>This image shows the listener and procedure interfaces that can be used along with the read requests for one of two reasons: 1. the read requests were made asynchronously so completion can be reported through a '''Procedure''', 2. the client wants to listen to changes in the result of the performed request. Listeners have a lifecycle determined by their disposedness.]]
  
 
=== Repairing corrupted database ===
 
=== Repairing corrupted database ===
Line 71: Line 84:
 
* start server
 
* start server
  
=== Class Diagrams ===
+
== Simantics Database Properties ==
[[File:db1.png|frame|center|480px|[[File:db1.graphml]]<br/><br/>Database session-level class hierarchy. Use these to manage the session and initiate read and write requests (transactions). Requests can be initiated either synchronously or asynchronously. Synchronous invocations will not return before the request has completed/failed while asynchronous requests will return immediately and completion/failure will be notified through a separate '''Procedure'''.]]
+
 
 +
While Simantics DB uses transactions, it does not completely conform to [[wikipedia:ACID|ACID]] (Atomicity, Consistency, Isolation, Durability) rules:
 +
 
 +
;Atomicity: Atomicity should be covered by checkpoints, journaling, and rollback, but these mechanisms are still under development. Currently, if something fails during write trasaction, changes are that part of the written data has already gone into the database. This work is targeted for the next release and possibly for an in-between service release.
 +
 
 +
;Consistency: There are several different levels of consistency in play in Simantics and in its semantic graph database. These are from lowest to highest:
 +
:;Semantic graph consistency: The database server (and client) will ensure all statements written in the database must be made up of valid resources. Duplicate statements cannot be created either.
 +
 
 +
:;Core/Layer0 consistency: As an example, a resource ''r'' in the database can be marked an ''InstanceOf'' some type ''t''. In order for ''r'' to be semantically consistent, ''r'' needs to have the properties and relations marked mandatory for it in ''t'' with basic Layer0 requirement specifications. These rules are often fairly simple and easily verifiable. This level of consistency is not ensured by the database server nor the client, but can be considered the responsibility of custom database client query/changeset listeners.
  
[[File:db2.png|frame|center|480px|[[File:db2.graphml]]<br/><br/>Classes related to accessing the graph database during read and write transactions. ''ReadGraph'', ''AsyncReadGraph'', ''WriteGraph'' and ''WriteOnlyGraph'' are the only way to access the actual statements and values in the database. ''ReadGraph'' is a good place to get started.]]
+
:;Domain-specific consistency: A database may contain domain-specific models that may have very complex consistency rules. Such consistencies are meant to be handled through [[org.simantics.scl|SCL Language]] and computing ''issues'' that are presented to the user. For example, some inconsistencies are caused by incomplete models which is a natural situation in the process of developing a model. We simply let the database be domain-specifically inconsistent but strive to make it possible to develop validations that inform the user of such inconsistencies or ''issues''.
  
[[File:db3.png|frame|center|480px|[[File:db3.graphml]]<br/><br/>This image shows all the different kinds of requests that can be performed through ''RequestProcessor'' and ''AsyncRequestProcessor''. Beginners should focus on interfaces '''Read<T>''' and '''Write'''. Note that these request classes have default implementations that should be extended instead of directly implementing the interfaces. See the classes for more info.]]
+
;Isolation: Simantics DB allows multiple reads or a single write transaction simultaneously, so it should follow this rule.
  
[[File:db4.png|frame|center|480px|[[File:db4.graphml]]<br/><br/>This image shows the listener and procedure interfaces that can be used along with the read requests for one of two reasons: 1. the read requests were made asynchronously so completion can be reported through a '''Procedure''', 2. the client wants to listen to changes in the result of the performed request. Listeners have a lifecycle determined by their disposedness.]]
+
;Durability: The Simantics database is journaled in order guarantee durability. However, there remains work to be done to achieve full durability. Journal corruption has been experienced and is being debugged and fixed.
  
 
== FAQ ==
 
== FAQ ==
  
{{questionanswer|'''Q:''' Why can't I initialize my Workbench/SWT UI within a synchronous database read request? When I try to do this, SWTError Invalid thread access is thrown. I used to be able to do this before!|Excerpt from [[trac:browser/db/trunk/org.simantics.db/src/org/simantics/db/RequestProcessor.java|RequestProcessor]] [[javadoc:org/simantics/db/RequestProcessor.html|javadoc]]: <blockquote>A client invoking any of the <code>syncRequest</code>-methods in this interface must not assume that the request is performed within the same thread that performed the <code>syncRequest</code> invocation. This is an implementation-specific matter.</blockquote>Granted, before 2009 the implementation was such that it would execute synchronous requests within the invoking thread but it is now specified as seen above. Note that you cannot even synchronously schedule access to another thread and use the original ReadGraph/AsyncReadGraph from there since database access is tied to the dedicated threads assigned for it.}}
+
{{questionanswer|'''Q:''' Why can't I initialize my Workbench/SWT UI within a synchronous database read request? When I try to do this, SWTError Invalid thread access is thrown. I used to be able to do this before!|Excerpt from [[svn:db/trunk/org.simantics.db/src/org/simantics/db/RequestProcessor.java|RequestProcessor]] javadoc: <blockquote>A client invoking any of the <code>syncRequest</code>-methods in this interface must not assume that the request is performed within the same thread that performed the <code>syncRequest</code> invocation. This is an implementation-specific matter.</blockquote>Granted, before 2009 the implementation was such that it would execute synchronous requests within the invoking thread but it is now specified as seen above. Note that you cannot synchronously schedule access to another thread and use the original ReadGraph/AsyncReadGraph from there since database access is tied to the dedicated threads assigned for it.}}
  
 
{{questionanswer|'''Q:''' My write transaction was interrupted by unexpected exception. Why am I still seeing parts of the unfinished write operation in my database?  What happened to rollback?|The current DB client implementation does properly support write request rollback, which unfortunately causes the DB client's view of the database to be corrupted. Also if your write operation is not small, even the server's view of the database may be corrupted. At the moment it looks like resolving this issue will be delayed until Simantics 1.2. Until then, the Simantics database cannot be considered for continuous use in any real-life applications.}}
 
{{questionanswer|'''Q:''' My write transaction was interrupted by unexpected exception. Why am I still seeing parts of the unfinished write operation in my database?  What happened to rollback?|The current DB client implementation does properly support write request rollback, which unfortunately causes the DB client's view of the database to be corrupted. Also if your write operation is not small, even the server's view of the database may be corrupted. At the moment it looks like resolving this issue will be delayed until Simantics 1.2. Until then, the Simantics database cannot be considered for continuous use in any real-life applications.}}
 +
 +
[[Category: Database Development]]
 +
[[Category: Tutorials]]

Latest revision as of 19:43, 3 September 2011

Quickstart

Client opens a database session

To open a client session to a Simantics database server you need to fetch a Driver (javadoc) from the Driver manager (javadoc).

The basic idea is much the same as in JDBC Driver and DriverManager.

<syntaxhighlight lang="java"> import org.simantics.db.Manager; import org.simantics.db.ServerAddress; import org.simantics.db.Session;

   // Try to load and register the Driver instance with the driver manager
   Class.forName("fi.vtt.simantics.procore.ProCoreDriver");
   // Connect to the server at the specified host and credentials.
   Session session = Manager.getSession("procore", new ServerAddress("localhost", port), username, password);

</syntaxhighlight>

Reading the database

Synchronous primitive read

<syntaxhighlight lang="java">

   Boolean readBooleanProperty(RequestProcessor processor, final Resource resource, final Resource property) {
       return processor.syncRequest(new Read<Boolean>() {
           public Boolean perform(ReadGraph graph) throws DatabaseException {
               return graph.getRelatedValue(resource, property);
           }
       });
   }

</syntaxhighlight>

Writing the database

Synchronous write requests

<syntaxhighlight lang="java">

   Resource createLibrary(WriteGraph graph) throws DatabaseException {
       Builtins b = graph.getBuiltins();
       // Create new Library instance. Use claim(s,p,inv,o)
       // instead of claim(s,p,o) for defining (s, InstanceOf, o)
       // to not create the inverse statement (o, HasInstance, s).
       Resource library = graph.newResource();
       graph.claim(library, b.InstanceOf, null, b.Library);
       // Give the library a name
       graph.claimLiteral(library, b.HasName, "New Library");
       // Attach the library to the specified container
       graph.claim(container, b.ConsistsOf, library);
   }
   class CreateLibrary extends AbstractWriteResult<Resource> {
       Resource container;
       public CreateLibrary(Resource container) {
           this.container = container;
       }
       public Resource perform(WriteGraph graph) throws DatabaseException {
           return createLibrary(graph);
       }
   }
   void createLibrary(RequestProcessor processor, Resource container) {
       processor.syncRequest(new CreateLibrary(container));
   }

</syntaxhighlight>

Class Diagrams

File:Db1.graphml

Database session-level class hierarchy. Use these to manage the session and initiate read and write requests (transactions). Requests can be initiated either synchronously or asynchronously. Synchronous invocations will not return before the request has completed/failed while asynchronous requests will return immediately and completion/failure will be notified through a separate Procedure.
File:Db2.graphml

Classes related to accessing the graph database during read and write transactions. ReadGraph, AsyncReadGraph, WriteGraph and WriteOnlyGraph are the only way to access the actual statements and values in the database. ReadGraph is a good place to get started.
File:Db3.graphml

This image shows all the different kinds of requests that can be performed through RequestProcessor and AsyncRequestProcessor. Beginners should focus on interfaces Read<T> and Write. Note that these request classes have default implementations that should be extended instead of directly implementing the interfaces. See the classes for more info.
File:Db4.graphml

This image shows the listener and procedure interfaces that can be used along with the read requests for one of two reasons: 1. the read requests were made asynchronously so completion can be reported through a Procedure, 2. the client wants to listen to changes in the result of the performed request. Listeners have a lifecycle determined by their disposedness.

Repairing corrupted database

When running the database in debug mode a complete journal of all the changes made to the database is kept. If an error is encountered during a change the erroneous command is written to the journal and the database will stop servicing requests. The journal can be used to initialize the database by reading it to an empty database. This can be done by:

  • rename journal.procore file to journalRepair.procore
  • delete or rename other *.procore files so that you have empty database
  • start server

Simantics Database Properties

While Simantics DB uses transactions, it does not completely conform to ACID (Atomicity, Consistency, Isolation, Durability) rules:

Atomicity
Atomicity should be covered by checkpoints, journaling, and rollback, but these mechanisms are still under development. Currently, if something fails during write trasaction, changes are that part of the written data has already gone into the database. This work is targeted for the next release and possibly for an in-between service release.
Consistency
There are several different levels of consistency in play in Simantics and in its semantic graph database. These are from lowest to highest:
Semantic graph consistency
The database server (and client) will ensure all statements written in the database must be made up of valid resources. Duplicate statements cannot be created either.
Core/Layer0 consistency
As an example, a resource r in the database can be marked an InstanceOf some type t. In order for r to be semantically consistent, r needs to have the properties and relations marked mandatory for it in t with basic Layer0 requirement specifications. These rules are often fairly simple and easily verifiable. This level of consistency is not ensured by the database server nor the client, but can be considered the responsibility of custom database client query/changeset listeners.
Domain-specific consistency
A database may contain domain-specific models that may have very complex consistency rules. Such consistencies are meant to be handled through SCL Language and computing issues that are presented to the user. For example, some inconsistencies are caused by incomplete models which is a natural situation in the process of developing a model. We simply let the database be domain-specifically inconsistent but strive to make it possible to develop validations that inform the user of such inconsistencies or issues.
Isolation
Simantics DB allows multiple reads or a single write transaction simultaneously, so it should follow this rule.
Durability
The Simantics database is journaled in order guarantee durability. However, there remains work to be done to achieve full durability. Journal corruption has been experienced and is being debugged and fixed.

FAQ

Q: Why can't I initialize my Workbench/SWT UI within a synchronous database read request? When I try to do this, SWTError Invalid thread access is thrown. I used to be able to do this before!

Excerpt from RequestProcessor javadoc:

A client invoking any of the syncRequest-methods in this interface must not assume that the request is performed within the same thread that performed the syncRequest invocation. This is an implementation-specific matter.

Granted, before 2009 the implementation was such that it would execute synchronous requests within the invoking thread but it is now specified as seen above. Note that you cannot synchronously schedule access to another thread and use the original ReadGraph/AsyncReadGraph from there since database access is tied to the dedicated threads assigned for it.

Q: My write transaction was interrupted by unexpected exception. Why am I still seeing parts of the unfinished write operation in my database? What happened to rollback?

The current DB client implementation does properly support write request rollback, which unfortunately causes the DB client's view of the database to be corrupted. Also if your write operation is not small, even the server's view of the database may be corrupted. At the moment it looks like resolving this issue will be delayed until Simantics 1.2. Until then, the Simantics database cannot be considered for continuous use in any real-life applications.