Difference between revisions of "Org.simantics.db"

From Developer Documents
Jump to navigation Jump to search
m (Created page with ''''org.simantics.db''' (SVN) provides access to versioned graph data. '''org.simantics.db.procore''' ([[svn:db/trunk/org.simantics.db.proc...')
 
 
(9 intermediate revisions by 2 users not shown)
Line 3: Line 3:
 
'''[[org.simantics.db.procore]]''' ([[svn:db/trunk/org.simantics.db.procore|SVN]]) offers an simple implementation of an TCP/IP based client to '''[[org.simantics.db.procore.server]]''' ([[svn:db/trunk/org.simantics.db.procore.server|SVN]])
 
'''[[org.simantics.db.procore]]''' ([[svn:db/trunk/org.simantics.db.procore|SVN]]) offers an simple implementation of an TCP/IP based client to '''[[org.simantics.db.procore.server]]''' ([[svn:db/trunk/org.simantics.db.procore.server|SVN]])
  
'''[[org.simantics.db.tests]]''' ([[svn:db/trunk/org.simantics.db.tests|SVN]]) provides small set of tests.
+
'''[[org.simantics.db.tests]]''' ([[svn:db/trunk/org.simantics.db.tests|SVN]]) contains unit tests for the client library.
 
 
== Introduction ==
 
 
 
[[File:db1.png|center|frame|[[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|center|frame|[[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|center|frame|[[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|center|frame|[[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.]]
 
 
 
== Quickstart ==
 
 
 
=== 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]).
 
 
 
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].
 
 
 
<source lang="java">
 
    // 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", InetSocketAddress.createUnresolved("localhost", port), username, password);
 
</source>
 
 
 
=== Reading the database ===
 
 
 
; Synchronous primitive read
 
<source 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);
 
            }
 
        });
 
    }
 
</source>
 
 
 
=== Writing the database ===
 
 
 
; Synchronous write requests
 
<source 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.claimValue(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));
 
    }
 
</source>
 
 
 
=== 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
 
  
 
== Reference ==
 
== Reference ==
  
 
=== [[Subgraph Extents]] ===
 
=== [[Subgraph Extents]] ===
=== [[Graph exchange format]] ===
+
=== [[Transferable Graph]] ===
 
=== [[Inverse Relations]] ===
 
=== [[Inverse Relations]] ===
 
=== [[Resource Adaptation]] ===
 
=== [[Resource Adaptation]] ===
 
=== [[Resource Serialization]] ===
 
=== [[Resource Serialization]] ===
 
=== [[Undo and Redo]] ===
 
=== [[Undo and Redo]] ===
=== [[Database_tutorial|Tutorial]] ===
+
=== [[Tutorial:_Database_Development|Tutorial]] ===
  
== 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:''' 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.}}
 
 
== Links ==
 
 
* [http://www.simantics.org/hudson/job/db-connector/ Continuous development builds]
 
* [http://www.simantics.org/hudson/job/db-connector-release/ Release builds]
 
  
 
== Download ==
 
== Download ==
Line 237: Line 148:
  
 
=Current Development=
 
=Current Development=
The next version 0.8 is currently under development.
 
* [https://www.simulationsite.net/trac/simantics/query?status=assigned&status=new&status=reopened&col=id&col=summary&col=status&col=type&col=priority&col=milestone&component=org.simantics.db&order=priority&version=0.8 Open 0.8 Tickets]
 
* [https://www.simulationsite.net/trac/simantics/query?status=closed&col=id&col=summary&col=status&col=type&col=priority&col=milestone&component=org.simantics.template&order=priority&version=0.8 Closed 0.8 Tickets]
 
 
 
 
Planned features:
 
Planned features:
* Rework Cluster Structure
+
* Rework Cluster Structure
  
 
Planned work:
 
Planned work:
* [https://www.simulationsite.net/trac/simantics/query?status=assigned&status=new&status=reopened&col=id&col=summary&col=status&col=type&col=priority&col=milestone&component=org.simantics.db&order=priority Open Tickets]
+
* [[redmine:projects/simantics/issues?query_id=10|Open Tickets]]
 
 
 
 
  
 
== Contact ==
 
== Contact ==

Latest revision as of 20:06, 30 October 2010

org.simantics.db (SVN) provides access to versioned graph data.

org.simantics.db.procore (SVN) offers an simple implementation of an TCP/IP based client to org.simantics.db.procore.server (SVN)

org.simantics.db.tests (SVN) contains unit tests for the client library.

Reference

Subgraph Extents

Transferable Graph

Inverse Relations

Resource Adaptation

Resource Serialization

Undo and Redo

Tutorial

Download

Version Date Download SVN Source Tag SVN Target Tag SVN Headless Tag
0.6.1 12.8.2009 hudson build svn:db/tags/0.6.1/
0.6.2 10.9.2009 [not available] svn:db/tags/0.6.2/ svn:db/tags/0.6.2.target/ svn:db/tags/0.6.2.dev/
0.6.3 10.9.2009 [not available] [not available] svn:db/tags/0.6.3.target/ svn:db/tags/0.6.3.dev/
0.6.4 9.10.2009 [not available] svn:db/tags/0.6.4/ [deprecated] [deprecated]
0.7.1 04.12.2009 [not available] svn:db/tags/0.7.1/ [deprecated] [deprecated]
0.7.2 13.01.2010 [not available] svn:db/tags/0.7.2/ [deprecated] [deprecated]

Change Log

13.01.2009

0.7.2

4.12.2009

0.7.1

  • Tested with Apros and Simantics products.
  • Supports win32.x86, linux32.x86 and linux64.x86 versions.
  • Protocol changed, not compatible with previous versions.
  • Database generation has changed, now database generation scripts are in org.simantics.db.build plug-in. Script build has the exact same interface as the old generate2 script. All data needed for building database is in org.simantics.db.build which must be as a project in your development workbench if you want to build new databases i.e. check out https://www.simulationsite.net/svn/simantics/db/tags/0.7.1/projects/org.simantics.db.build project.
  • Plugin metainformation must be updated to use the new version.
  • DatabaseUtil has been modified slightly:

import org.simantics.db.Manager;

       String templateBundle = Manager.getTemplateBundle();
       String templatePath2;
       try {
           templatePath2 = Manager.getTemplatePath();
       } catch (DatabaseException e) {
           throw new FileNotFoundException("No template plugin available:" + e.getMessage());
       }
       String templateMask = Manager.getTemplateMask();
       Bundle bundle = Platform.getBundle(templateBundle);
       if (bundle == null)
           throw new FileNotFoundException("No template plugin available ");

9.10.2009

0.6.4

  • Fixed bug with setting value to resource in server (ProCoreServer). NOTE: Only linux 32 bit version compiled.

10.9.2009

0.6.3

  • Fixed linux 32 bit version bug.

10.9.2009

0.6.2

  • Highly unstable release.
  • First release that has corresponding target platform.
  • Linux 32 bit version does not work.
  • Writeonly cluster API does not work if clusters are also read during updates.
  • Database corrupts after short modelling period.
  • Database files can not be transferred between different operating systems.

12.8.2009

0.6.1

  • First so called "stable" release for a long time.

Roadmap

  • 1.0RC1 (2010/02/19)
    • Cluster optimization (Done 12.2.)
    • Refresh of direct server clients when database changes
    • Blob API and local (workspace based) implementation (partly Done i.e. API 12.2.)
    • Team features view with (Partly done but not tested yet 12.2.)
      • Publish/synchronize all functionality
      • Simple list of configuration history
    • Undo API
    • Virtual graph API support (Partly done 12.2. -> Antti's work, NO DOCUMENTATION AVAILABLE)
  • 1.0 (2010/03/17)
    • Bug fixes
  • 1.1 (2010/07/09)
    • Team features view with
      • Partial publish/synchronize
    • Undo functionality
    • Remote Blob (datbase based) implementation
  • 1.2 (2010/09/01)
    • Team features view with
      • Conflict detection and resolution
    • Offline reclustering
    • Database debugging tools
      • At least a check of database and report (cf. chkdsk)
  • 2.0 (2011(02/01)
    • Recluster functionality
    • Offline mode
    • Access control

Current Development

Planned features:

  • Rework Cluster Structure

Planned work:

Contact

  • kalle.kondelin@vtt.fi
  • antti.villberg@semantum.fi