View source for FAQ for Wandora user

This FAQ is targeted to Wandora user and contains answers for some common problems you may face while experimenting with Wandora. There is also another [[General FAQ|FAQ]] answering more general questions about Wandora. See also [http://www.wandora.org/wandora/forum/index.php Wandora forum] for additional help.


==I get java.lang.NullPointerException while opening a project in Wandora==

This happens if you try to open XTM or LTM Topic Map (or unsupported file) with Open Project option. Plain XTM and LTM Topic Maps are not Wandora project files. [[How to save and load project|Wandora project file]] is a zip package of XTM files with special options.xml. To import XTM and LTM Topic Maps to Wandora you should use '''File > Import > Merge topic map''' feature.

== The layer is red! ==
Layers locate in bottom-left corner of Wandora window. A layer represents single topic map open in Wandora. Layers are usually gray. Sometimes a layer may be dark red. This happens only with [[Database topic map|database topic map layers]] when Wandora is not able to connect the given database. Right click the layer, select '''Configure layer...''' and correct database settings.

==When I try to edit a topic Wandora throws org.wandora.topicmap.TopicMapReadOnlyException==
You have locked current layer. To resolve this just unlock current layer or select another (unlocked) layer and try again.

==I try to unlock a layer but it doesn't unlock!==
This happens with database and query topic map layers.

Wandora notices automatically if the database user has no write rights to the database and keeps the layer locked even if the user clicks the lock icon in layer stack. To resolve problem reconfigure your layer and change the database user or change the database user rights.

[[Query topic map]]s are always locked as they contain algorithmically generated associations and topics. To edit query topic map edit the query that generates the topic map or edit topic maps used as a source for queries.

==I can't see topic's associations, classes, instances, names or occurrences in topic panel==
Check that you have toggled the topic element visible in '''View''' menu. Check also that you  are using a [[Topic panels|topic panel]] that is capable to view the elements you are missing. Some topic panels may not contain visual representation for the missing element. For example Graph topic panel does not view topic's subject identifiers. [[Topic panels]] are listed in '''View > Topic panels'''. [[Traditional topic panel]] is a safe choice as it views all elements of a topic (unless you have toggled some elements invisible).

==Wandora does not delete topic==
Wandora does not allow topic deletion if the topic is a role in any association or an occurrence (text data) type in any occurrence. Delete such associations and occurrences first and try again. Another reason for unsuccessful deletion may be the selected layer. Check that the topic is included in selected layer. Check also that any other layer does not contain merged topic. [[Layer distribution]] may help here. You have to delete the topic separately in every layer.

==Wandora does not change topic's base name, variant name or occurrence data==
Check if there exists a merged topic in layers above. Check also if the topic above already has a base name, variant name or occurrence data with the same type and scope. [[Topic's layer distribution]] may help here. Change the base name, variant name or occurrence data of the top layer or remove base name, variant name or occurrence data of layers above.

This problem is discussed also in Wiki page [[Layer order and arranging layers]].

==Base name is red!==
The base name locates in merged topic but not in current layer. Changing the base name now does not change viewed base name but adds base name to the topic in current layer. Depending on the layer order the effect is
* Base name does not change but stays red. The merged topic above overrides the topic in current layer.
* Base name changes and the color of the base name changes to black. The merged topic is below current layer and you have overriden the base name in merged topic. Toggling the visibility of current layer changes the base name to the base name found in layer below.

==Base name does not change when I make base name with subject identifier==
Generating base name with subject identifier does not change existing base names. To force base name generation, remove old base names before base name generation. To remove base names

* Select topics
* Start '''Topics > Base names > Remove base names...'''

==Topic is red!==
Topic doesn't exist in current layer! Editing the topic now creates a merged topic to the current layer.

==I am not able to delete topic's subject identifier==
Wandora does not allow SI deletion if topic has only one SI. Add second SI to the topic and remove the first one. Ensure also that you have selected same topic map layer where the topic locates.

To make the picture more complicated, a topic may be a merged one i.e. it locates in several layers. To ensure which subject identifiers locate in current layer, you might find it useful to toggle all other layers invisible.

==Topic is [null]==
This happens with association tables when association has no player with expected role. Wandora tries to optimize association visualization by placing multiple similar (=same association type) associations into a single topic table. Now, if you have two associations with same type but different roles, the association table has columns for all roles found in these associations and the column contains '''[null]''' if association has no player with column role.

==Topic is [removed]==
You probably see this most often in Finder's result set. When topic is shown as '''[removed]''', the topic table cell contains removed topic. Topic may have been removed explicitly by '''Delete topic''' operation or implicitly by merging the topic to another. If you perform the Finder search again the result set is updated and should not contain '''[removed]''' topics.

==I try to add association but the association editor window doesn't work==

Updated 2008-03-07: This should '''not''' be an issue anymore as association editors have been merged! Current Wandora distribution has only one association editor that resembles old schemaless association editor.

Old answer: Wandora has two association editors. You probably opened the '''schema association editor''' and have not defined required [[Schema|schema]] associations. Try starting the '''schemaless association editor''' selecting '''Add schemaless association'''.

==I live in Sweden and would like to see Swedish as the first variant name type (occurrence type)==
Variant name types are arranged in alphabetical order by default. To change the order, open topic '''Language SE''' under '''Wandora language''' and add '''_Swedish''' (Note the underscore character prefix) as the '''Sort name''' for the topic. Now Swedish sorts before English, Finnish, and Language independent.

==I would like use language X in variant names and occurrences==
See documentation at [[How to add a language to Wandora]].

==Oops, I made a mistake. Is there any kind of Cancel or Undo in Wandora?==

Yes, select menu option '''Edit > Undo'''. Notice, the undo covers only topic map operations. Deleting a topic map layer is not count as a topic map operation, unfortunately.

==How do I add my topic to topic tree==
Topics are arranged in topic tree along super-subclass and class-instance relation. Tree root is '''Wandora class''' with subject identifier '''http://www.wandora.org/core/wandoraclass'''.

You can add your topic to the topic tree by
* Adding '''Wandora class''' as a class (type) to your topic.
* Associating your topic to '''Wandora class''' with super-subclass association.

==How do I export topic map in LTM format==
Start topic map export and give export file name extension '''LTM''' (extension can be in lower case). Wandora chooses file format automatically using the file extension. By default Wandora exports topic map in '''XTM 2.0''' format.

==How do I export topic map in XTM 1.0 format==
Start topic map export by selecting a menu option '''File > Export > Export topic map...''' and give name extension '''XTM1''' (extension can be in lower case) to the exported file. Wandora chooses file format automatically using the file extension.

==I am using regular expressions to modify X. What kind of regular expressions Wandora uses?==

Wandora uses Java's native regular expressions that resemble Perl's regular expressions. Read more here:

* http://java.sun.com/javase/6/docs/api/java/util/regex/Pattern.html

==Wandora application window doesn't open==

Wandora remembers application window's last location on screen. If you change screen resolution between use sessions, it is possible that Wandora opens application window outside your current screen area. To restore the application window location:

* Close Wandora application
* Open Wandora options file '''resources/conf/options.xml''' in any text editor (or in XML editor)
* Find elements '''window > x''' and '''window > y''' and change their content to '''0'''.
* Save changes and
* Run Wandora application

If you have not changed screen size, I suggest you start Wandora with shell script (bin/wandora.bat for example) and check if application generates any debug log to shell console during startup.

== Application window is broken ==

Sometimes Wandora may break it's configuration file. Configuration file contains important application settings and the application doesn't work if the file corrupts. Configuration file (or options file as it is called above) is located at '''resources/conf/options.xml'''. Usually it's size is more than 50 kilos. If your configuration file is broken, it's size is probably only few kilos. To correct the configuration file, remove broken file and rename file's copy or original version as '''options.xml'''. If renaming didn't remove the problem, and your options file '''is''' broken, download a fresh version of Wandora application.

* [[Wandora's configuration file]]

== Wandora throws OutOfMemory exception ==

Start Wandora with scripts in '''bin''' folder. Try '''Wandora-huge'''. Script starts Wandora application with a memory footprint of 1.4G. If you are running Wandora in a 64bit machine (with a 64bit operating system and with a 64bit Java version) you can also use larger memory footprints in Java.

== How do I change the layout of WWW pages provided by Wandora server? ==

You have to edit WWW page template at '''build/resources/gui/server/topic/templates/viewtopic.vhtml'''. Template file can be edited with any text editor. Template file is a [http://velocity.apache.org Velocity template file].

== How do I change the layout of topic prints? ==

Topic is printed using [http://velocity.apache.org Velocity template files] at '''build/resources/gui/printtemplates'''. You may edit available templates with any text editor application or you can create new template. Wandora scans template folder automatically. Template name is specified by template's first line:

  ##TEMPLATE-NAME: This is template name

== Can I change icons the application uses? ==

Wandora uses graphic icons stored in '''build/resources/gui/icons'''. Icons are PNG image files. You can edit icons in this resource folder. However, you can not change file names without recompiling the application.

== How to view all variant names of a topic? ==

Open topic in traditional topic panel, right mouse click title of Variant names box, and choose menu option '''View > View all scopes'''.

== How to view variant name matrix? ==

To view variant name matrix, right mouse click title of Variant names box, and choose menu option '''View > View schema scopes'''.

== Number of variant names is not equal to viewed variant names ==

Number of variant names is viewed beside the title of variant name box in traditional topic panel. Number is equal to the count of '''all''' variant name scopes found in current topic. However, variant name box may view only schema based variant names. To view all variant names of a topic, right mouse click title of Variant names box, and choose menu option '''View > View all scopes'''.

== What are those Hide level occurrences? ==

Wandora's base ontology topics include occurrences typed as '''Hide level'''. Occurrences were used to hide schema topics a loooong time ago. At the moment '''Hide level''' occurrences are not used to anything.

== I need to use a proxy server for outside network connections, how do I setup that? ==

To do this you need to specify the proxy server on the command line when starting Wandora. Easiest way to do this is to modify the existing startup scripts ('''bin/Wandora.bat''' or '''bin/Wandora.sh''' or the similar higher memory versions). You need to add the command line parameters '''-Dhttp.proxyHost=server''' and '''-Dhttp.proxyPort=port''' somewhere on the final line. Replace the words server and port to match your proxy server settings.

So the final line might look like this on Windows (the .bat file)

  "java" -Dhttp.proxyHost=10.0.0.2 -Dhttp.proxyPort=8080 -Xms750m -Xmx1000m -classpath %WANDORACLASSES% -Djava.library.path="lib/fmj/native" -Dorg.wandora.mediafw="FMJ" org.wandora.application.Wandora %*

or for the shell script (.sh)

  java -Dhttp.proxyHost=10.0.0.2 -Dhttp.proxyPort=8080 -Xms750m -Xmx1000m -Dorg.wandora.mediafw="GST" -classpath $WANDORACLASSES org.wandora.application.Wandora $1