Skip to Content

Changes for page TopicMap Engine

Last modified by christoph_lechleitner@iteg_at on 2013-02-02 07.31:25
From version 1.1
edited by christoph_lechleitner@iteg_at
on 2012-06-14 06.08:40
Change comment: There is no comment for this version
To version 2.1
edited by 5fbc055b7cc103006957e1ae
on 2012-06-15 03.36:43
Change comment: There is no comment for this version

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.christoph_lechleitner@iteg_at
1 +XWiki.5fbc055b7cc103006957e1ae
Content
... ... @@ -1,37 +1,242 @@
1 -(% class="contentLayout" data-atlassian-layout="{~"name~":~"pagelayout-two-right~",~"columns~":[~"large~",~"aside~"],~"header~":true,~"footer~":true}" %)
1 +(% style="" %)
2 +//**TM2JDBC** is a implementation of the TopicMaps API ([[TMAPI 2.0.2>>url:http://www.tmapi.org/2.0/||shape="rect"]]). It is a fast, production-grade Topic Maps Engine with a small dependency footprint. TM2JDBC uses a relational database to store its data, and is verified to operate with Apache Derby, MySQL, MSSQL Server and Oracle databases.//
3 +
4 +(% style="" %)
5 +TM2JDBC is released in version 1.0.1. This release features some dependency updates and minor corrections of inconsistencies within the code, but is fully compatible to version 0.9.0.
6 +
7 +(% style="" %)
8 +* Updated TMAPI dependency to version 2.0.2 (the prior version already was compliant with TMAPI 2.0.2, but still referenced a snapshot as the final library was not released)
9 +* OSGi support – The library now comes packaged as an OSGi-bundle, which allows it to be deployed to your OSGi container of choice. This has no side-effencts on non-OSGi projects
10 +* Updated clazzes.org-dependencies to the current version
11 +
12 +(% style="" %)
13 +If you are using maven, you can use the new version by adding the following snippets to your {{code language="none"}}pom.xml{{/code}} file:
14 +
15 +(% style="" %)
2 2  (((
3 -(% class="header" %)
4 -(((
5 -This is the home of the TopicMap Engine space.
17 +{{code language="none"}}
18 +<dependency>
19 + <groupId>org.clazzes</groupId>
20 + <artifactId>tm2jdbc</artifactId>
21 + <version>1.0.1</version>
22 +</dependency>
6 6  
7 -To help you on your way, we've inserted some of our favourite macros on this home page. As you start creating pages, blogging and commenting you'll see the macros below fill up with all the activity in your space.
24 + 
25 +...
26 + 
27 +<repository>
28 + <id>org.clazzes</id>
29 + <name>Clazzes.org repository.</name>
30 + <url>http://maven.clazzes.org</url>
31 +</repository>
32 +{{/code}}
8 8  )))
9 9  
10 -(% class="columnLayout twoColumns" %)
35 +(% style="" %)
36 +If you do not use maven, you can download the .jar files manually from our repository at [[http:~~/~~/maven.clazzes.org/org/clazzes/tm2jdbc>>url:http://maven.clazzes.org/org/clazzes/tm2jdbc||shape="rect"]].
37 +Alternatively, you can check out the sources directly from our SVN Repository:
38 +
39 +{{code language="none"}}
40 +http://svn.clazzes.org/svn/topicmaps/trunk/tm2jdbc/
41 +
42 +{{/code}}
43 +
44 +(% style="" %)
45 += {{id name="TopicMapEngineHome-SetupandUsageNotes"/}}Setup and Usage Notes =
46 +
47 +(% style="" %)
48 +TM2JDBC needs a relational database and the appropriate JDBC 4.0 compatible driver to function. However it does not have any direct dependencies to a specific JDBC connector. Instead, it expects a {{code language="none"}}javax.sql.DataSource{{/code}} to be set as a property (see below), which it will use to obtain database connections. Although the engine should function with any DataSource implementation, we strongly recommend to use the [[Apache Commons DBCP>>url:http://commons.apache.org/dbcp/||shape="rect"]] library. A rudimentary set-up for a {{code language="none"}}BasicDataSource{{/code}} can be found in the class {{code language="none"}}org.clazzes.tm2jdbc.util.test.DataSourceProvider{{/code}}.
49 +
50 +(% style="" %)
51 +=== {{id name="TopicMapEngineHome-ProvidingaDataSource"/}}Providing a DataSource ===
52 +
53 +(% style="" %)
54 +To handle database connectivity, the TM2JDBC engine relies on a{{code language="none"}}javax.sql.DataSource{{/code}} to be set for the property ##(% class="nolink" %)http:~/~/psi.clazzes.org/topicmaps/db-connection/datatsource(%%)## in the Factory (attempting to call {{code language="none"}}newTopicMapSystem(){{/code}} without the property being set causes an{{code language="none"}}IllegalStateException{{/code}} to be thrown. The property string can also be accessed directly via the Enum object{{code language="none"}}org.clazzes.tm2jdbc.voc.PropertyKey.CONNECTION_DATASOURCE{{/code}}. The most basic setup could look like this:
55 +
56 +(% style="" %)
11 11  (((
12 -(% class="cell large" %)
13 -(((
14 -(% class="innerCell" %)
15 -(((
16 -{{recently-updated/}}
58 +{{code language="java"}}
59 +BasicDataSource datasource = new BasicDataSource();
60 +datasource.setDefaultAutoCommit(false);
61 +
62 +datasource.setInitialSize(4);
63 +datasource.setMinIdle(1);
64 +datasource.setMaxIdle(8);
65 +datasource.setMaxActive(8);
66 +datasource.setMaxWait(3000);
67 +
68 +datasource.setDriverClassName(driver);
69 +
70 +datasource.setPassword(password);
71 +datasource.setUsername(user);
72 +datasource.setUrl(url);
73 +
74 +TopicMapSystemFactory factory = TopicMapSystemFactory.newInstance();
75 +factory.setProperty(PropertyKey.CONNECTION_DATASOURCE.getURI(), dsProvider.getDataSource());
76 +
77 +TopicMapSystem system = factory.newTopicMapSystem();
78 +{{/code}}
79 +
80 +
17 17  )))
18 -)))
19 19  
20 -(% class="cell aside" %)
83 +(% style="" %)
84 +=== {{id name="TopicMapEngineHome-RunningtheDBSetupUtilityincommandline"/}}Running the DBSetup Utility in commandline ===
85 +
86 +(% style="" %)
87 +The engine provides a setup-utility to create the tables it needs in a provided database schema. This utility can either be run as a standalone java executable (in the command line, via a shell script etc.) or instanciated as a Java Object by your own code (see below). The class name is {{code language="none"}}org.clazzes.tm2jdbc.jdbc.setup.DBSetup{{/code}}. For testing and development, it may be useful to run the setup utility in commandline or the development evironment of your choice. The standard use-case is to set up the database schema, but you can also use it to drop all tables in the schema.
88 +Making sure that the appropriate database drivers are added to the classpath, the accepts arguments like this:
89 +
90 +(% style="" %)
21 21  (((
22 -(% class="innerCell" %)
23 -(((
24 -====== {{id name="TopicMapEngineHome-Navigatespace"/}}Navigate space ======
92 +{{code language="none"}}
93 +DBSetup {derby|mssql|mysql|oracle} {{ [-h <HOSTNAME>] [-t <PORT>] [-n <SCHEMA NAME>] } | {--url <DATABASE-URL>}} -u <USER> -p <PASSWORD> [-d <DRIVER-CLASSNAME> ] [--debug] [--drop|--force-drop] [--nosetup]
94 +{{/code}}
95 +)))
25 25  
26 -{{locationSearch reference="WebHome"/}}
97 +(% style="" %)
98 +Below is a listing of all argument flags and the default values:
27 27  
28 -{{documentTree root="document:TME.WebHome"/}}
100 +(% style="" %)
101 +|=(((
102 +Flag
103 +)))|=(((
104 +Default Value
105 +)))|=(((
106 +Description
29 29  )))
108 +|(((
109 +{{code language="none"}}
110 +-h
111 +{{/code}}
112 +)))|(((
113 +127.0.0.1
114 +)))|(((
115 +The hostname/address of your database server. **Caution: When using Oracle database systems, the hostname is interpreted as a TNS name, which is resolved to an IP locally. Alternatively, you may also specify a string like{{code language="none"}}<IP-HOST>/<SID>{{/code}}**
30 30  )))
117 +|(((
118 +{{code language="none"}}
119 +-t
120 +{{/code}}
121 +)))|(((
122 +//default port//
123 +)))|(((
124 +If omitted, the default port for the specified database server is used
31 31  )))
32 -
33 -(% class="footer" %)
34 -(((
126 +|(((
127 +{{code language="none"}}
128 +-n
129 +{{/code}}
130 +)))|(((
131 +topicmaps
132 +)))|(((
35 35  
36 36  )))
135 +|(((
136 +{{code language="none"}}
137 +--url
138 +{{/code}}
139 +)))|(((
140 +//none//
141 +)))|(((
142 +Alternatively to entering the hostname, port and schema name, you can supply the jdbc url directly.
37 37  )))
144 +|(((
145 +{{code language="none"}}
146 +-u
147 +{{/code}}
148 +)))|(((
149 +//none//
150 +)))|(((
151 +You must enter a username and password
152 +)))
153 +|(((
154 +{{code language="none"}}
155 +-p
156 +{{/code}}
157 +)))|(((
158 +//none//
159 +)))|(((
160 +
161 +)))
162 +|(((
163 +{{code language="none"}}
164 +-d
165 +{{/code}}
166 +)))|(((
167 +//default driver class//
168 +)))|(((
169 +If you want to use a different driver class than the default, you can specify the fully qualified classname using this flag. Make sure that the class is added to the classpath.
170 +)))
171 +|(((
172 +{{code language="none"}}
173 +--debug
174 +{{/code}}
175 +)))|(((
176 +//false//
177 +)))|(((
178 +Produces a verbose output
179 +)))
180 +|(((
181 +{{code language="none"}}
182 +--drop
183 +{{/code}}
184 +)))|(((
185 +//false//
186 +)))|(((
187 +Drops all tables in the schema, causes the utility to fail on errors
188 +)))
189 +|(((
190 +{{code language="none"}}
191 +--force-drop
192 +{{/code}}
193 +)))|(((
194 +//false//
195 +)))|(((
196 +Drops all tables in the schema, ignoring any errors (Use to clean the schema if it was corrupted or not created completely)
197 +)))
198 +|(((
199 +{{code language="none"}}
200 +--nosetup
201 +{{/code}}
202 +)))|(((
203 +//false//
204 +)))|(((
205 +Skip setting up the schema.
206 +)))
207 +
208 +(% style="" %)
209 +=== {{id name="TopicMapEngineHome-RunningtheDBSetupUtilityinJava"/}}Running the DBSetup Utility in Java ===
210 +
211 +(% style="" %)
212 +The database setup-utility also can be run in java. For this case it provides a constructor which takes a {{code language="none"}}javax.sql.DataSource{{/code}}, and provides the methods {{code language="none"}}setUpDB(boolean debug){{/code}} and {{code language="none"}}dropAllTables(boolean supressErrors){{/code}}. It is recommended to use these instead of running the {{code language="none"}}main(String[] args){{/code}} method with the appropriate arguments.
213 +
214 +(% style="" %)
215 +=== {{id name="TopicMapEngineHome-JUnittesting"/}}JUnit testing ===
216 +
217 +(% style="" %)
218 +TMAPI provides an extensive suite of Testcases to assure compliancy, which is also included in the TM2JDBC package. As the original tests were not conceived for engines which are based on an RDBMS, the {{code language="none"}}setUp(){{/code}} and {{code language="none"}}tearDown(){{/code}} methods where modified to initialize and drop the database schema between every test. You are welcome to subject the engine to additional tests (we would especially appreciate you to share the results with us), and for this purpose TM2JDBC provides the utility class{{code language="none"}}org.clazzes.tm2jdbc.util.test.DataSourceProvider{{/code}} (depends on Apache commons DBCP).
219 +It is recommended to use this utility in all test cases as follows:
220 +
221 +(% style="" %)
222 +(((
223 +{{code language="java"}}
224 +protected DataSourceProvider dsProvider;
225 +
226 +protected void setUp() throws Exception {
227 +super.setUp();
228 +if (dsProvider == null) {
229 +dsProvider = DataSourceProvider.getProvider();
230 +dsProvider.setUpDB();
231 +
232 +//set up factory etc. here ...
233 +factory.setProperty(PropertyKey.CONNECTION_DATASOURCE.getURI(), dsProvider.getDataSource());
234 +//...
235 +}
236 +}
237 +
238 +protected void tearDown() throws Exception {
239 +dsProvider.dropDB();
240 +}
241 +{{/code}}
242 +)))
Confluence.Code.ConfluencePageClass[0]
Id
... ... @@ -1,1 +1,1 @@
1 -689687
1 +689686
URL
... ... @@ -1,1 +1,1 @@
1 -https://clazzes.atlassian.net/wiki/spaces/TME/pages/689687/TopicMap Engine Home
1 +https://clazzes.atlassian.net/wiki/spaces/TME/pages/689686/TopicMap Engine Home