FAQ's

  1. How do I add a new regular (not dynamic) column in a table?
  2. How do I add a new dynamic column to a table?
  3. How do I setup a new scoring strategy?
  4. How do I unsign a jar file?
  5. How do I figure out what directory on the images server a scan is using?
  6. Where is the TMAJ_Server.srv file? Is it missing?
  7. I get an FileNotFoundException in TMAJ when I connect to TMAJ_Server.srv
  8. Do I need to use the Tomcat Administration or Tomcat Manager applications?
  9. What does this error mean: "Server returned HTTP response code: 500 for URL"?
  10. What does this error mean: java.io.IOException: Server returned HTTP response code: 401 for URL ?
  11. I forgot my password, or I get the error message "Bad Username or Password. Could not log on to TMAJ."
  12. TMAJ can't connect to the database.  What's wrong?
  13. How do I fix a "java.sql.SQLException: ORA-01861: literal does not match format string" error?
  14. Do I need to install the "Apache Tomcat Native library which allows optimal performance"?
  15. How do I create my own key to sign a jar file?
  16. How do I upgrade to a new version of TMAJ?
  17. Why  isn't Tomcat finding a URL?
  18. Why doesn't Tomcat reflect the changes I made in the source code?
  19. Why does my JNLP file come up as text instead of launching Java Web Start?
  20. What IDE is used to develop TMAJ?
  21. What does this error mean: "java.net.ConnectException: Connection refused: connect"?
  22. How do I backup my data in TMAJ?
  23. How do I backup my TMAJ installation?
  24. Does TMAJ have any database triggers?
  25. Why is Tomcat unable to read files on the network drive?
  26. Why do I get the error: java.lang.IncompatibleClassChangeError: Found class com.sun.image.codec.jpeg.JPEGImageEncoder, but interface was expected?


1) How do I add a new regular (not dynamic) column in a table?

  1. Add the column in the database.   This can be down using the ALTER command in sql, or by using a GUI provided by the creaters of your database. 
  2. Locate the JBean class for the table.  For example, if you are adding a column to the Specimens table, the class would be SpecimenBean. 
  3. Locate the array of TFields given by the getFieldsArray() method.  You will need to add the name of the column and type of the column to this array. 
    For example, if you were adding a field called EmployeeNumber, you would add a TField that looked like:
           new TField("EmployeeNumber",TFieldType.INTEGER)
    Note: You should add this on to the end of TFields array.  If you don't want the field appearing at the end, however, you can insert it somewhere else.  However if you do this you have to make sure that  any of the methods that return this field like:
         private static TField getEmployeeNumberField(){
            return FIELDS[1];
        }
    still return the right field.


2) How do I add a new dynamic column to a table?

There are only 3 tables with dynamic fields: Specimens, TissueDiagnosis, and ScoredImages.  There is no need to modify the database.  Use the MetaData application to add a dynamic field.

3) How do I setup a new scoring strategy?

Currently there is no way to do this through the application GUI.  You must do it through the database.
  1. Insert a new ScoringStrategy record in the ScoringStrategies table
    INSERT INTO ScoringStrategy (ScoringStrategyName) VALUES ('My New Scoring Strategy')  # assume ScoringStrategyID is auto-assigned 7
  2. Insert the fieldnames for this record in the ScoredImageFields table.  When adding fieldnames for a ScoringStrategy, make sure you leave the TissueTypeID NULL.  Only give a value to the ScoringStrategyID field in the ScoredImageFields table.  You will note that all records in the ScoreImageFields table have either a value for TissueTypeID or ScoringStrategyID: one or the other, but not both.
    INSERT INTO ScoredImageFields (FieldName, ScoringStrategyID) VALUES ('Field A', 7)  # assume FieldID is assigned 88
  3. Insert the enumerations for those fieldnames in the ScoredImageEnums table.
    INSERT INTO ScoredImageEnums (FieldID, EnumName) VALUES (88, 'Choice 1');
    INSERT INTO ScoredImageEnums (FieldID, EnumName) VALUES (88, 'Choice 2');

4) How do I unsign a jar file?

The quickest way to do this is get the WinZip program.  Open up the jar file with WinZip.  Locate the files in the meta-inf directory and delete all the signature files.  The signature files are basically all the files in the meta-inf directory except the manifest.mf file.  They will have extentions of .dsa and .sf. 

Another (slower) way is to uncompress the entire jar file, delete the signature files, and then jar the file back up again:
  1. Create a temporary directory to do this:
    mkdir temp
    copy tmaj.jar temp
    cd temp
  2. Uncompress the jar file and then delete it
    jar -xvf tmaj.jar
    del tmaj.jar
  3. Delete the signature files in the meta-inf directory
    del meta-inf\*.dsa
    del meta-inf\*.sf
  4. Recreate the jar file from the uncompressed files:
    jar -cvf tmaj.jar .


5) How do I figure out what directory on the images server a scan is using?

Every scan has a unique ArrayBlockID, Cut#, and Scan#.   Once you have the scanID, you can use the ArrayManager application to determine what the ArrayBlockID, Cut#, and Scan# is.  If you have this information, you will be able to go to your images directory and locate it.  No 2 directories should have the same ArrayBlockID, Cut#, and Scan#.  See directory naming for more details.   If you do have 2 or more directories with the same scan info in your images directory,  or are otherwise confused as to which images directory TMAJ is using, see below.

Using the GUI:

1)  Open the Images app
2)  Locate the ScanID in question
3)  Create a new session under the scanID
4)  Open the session
5)  Go to the ArraySlide window, then the menu, and open up the Data Table.
6)  Click the Show/ Hide columns button, and unhide the column "DirectoryPath"
7)  You will be able to see what directory the scan is using

Using the Database:

You can either find out in the database by doing a query like:
SELECT * FROM ArrayImages WHERE ScanID = 121

The scanID of each session will be shown in the Projects window in the Images application.   Then, look what the value of the DirectoryPath field is.  That will tell you what directory TMAJ is using.


6) Where is the TMAJ_Server.srv file? Is it missing?

No.  There isn't a TMAJ_Server.srv file.  Tomcat maps this filename to another filename.   One might think the file exists because the URL used to connect to Tomcat is something like:
http://www.myserver.com:8080/tmaj/servlet/TMAJ_Server.srv

Tomcat actually maps the TMAJ_Server.srv file to the class CommandServlet.  (If you're curious, this is done in the web.xml file.)

7) I get an FileNotFoundException in TMAJ when I connect to TMAJ_Server.srv.

You're exception looks something like this:
java.io.FileNotFoundException: http://localhost:8080/tmaj/servlet/TMAJ_Server.srv

If you point your web browser (like FireFox) to that URL, you should see a webpage.  If you don't, TMAJ will not work. 

You are probably getting this error because the TMAJ files for Tomcat have been placed in the wrong place.
In the manual, double check your steps where you setup the directory structure under tomcat with the TMAJ files.

Also, it might be possible you set the ServletURL wrong in the client.config file.  The client.config file is found in the jar file.  If you are trying to connect to TMAJ from a machine other the server, you should have set this variable. See the manual for more details.

8) Do I need to use the Tomcat Administration or Tomcat Manager applications?

No.  The only setup  you have to do with Tomcat is put the files in the proper place.  You may have to do a restart of Tomcat, but that is it.  If you open these applications you may see them referring to data sources, jdbc, and other tidbits.  These have nothing to do with TMAJ.

9) What does this error mean: "Server returned HTTP response code: 500 for URL"?

This means there was an initialition error on the server (Tomcat).  You can see the full details of the error inside Tomcat's log files directory. The default directory on Windows for this is:
C:\Program Files\Apache Software Foundation\Tomcat 5.5\logs

Locate the log file with the most recent "Date Modified" attribute.  Open the file and it should give an error message (or exception) detailing why the initialation of the TMAJ server failed.

10) What does this error mean: java.io.IOException: Server returned HTTP response code: 401 for URL ?

This error is given when you execute an 'ant reload' (or some other target that depends on a reload) and you supplied the wrong username and password for tomcat in your compile.properties file.  You can find the usernames and passwords for Tomcat in the file:
tomcat-users.xml
Tomcat has its own usernames and passwords to access it.  These usernames and passwords are completely different from the database username and password (i.e. username = dba, password = sql), which are in turn different from the usernames and passwords used to log on to the TMAJ GUI.
Remember to restart Tomcat after changing any information in the tomcat-users.xml file or else the changes will not take effect.
You can verify that you are using the proper username and password to log on to Tomcat by going to your tomcat homepage at:
http://localhost:8080   [the address may be different depending on your installation]

11) I forgot my password, or I get the error message "Bad Username or Password. Could not log on to TMAJ."

You have 2 options to fix this.

Option #1:
Contact a TMAJ administrator.  The administrator can log on, go to the administrator application, then the "users" tab, then click "Assign Password" to give you a new password.

Option #2:
  1. Go into the actual database (Sybase, MySQL, Oracle, etc.)
  2. Run this SQL Statement:
    UPDATE Users SET Password = '0DPiKuNIrrVmD8IUCuw1hQxNqZc='  WHERE Username = 'myUserName'
    Change myUserName to the username you use to log on to TMAJ.  The password is actually the hash of the string admin.  The database does not store the actual password, but rather the hash of the password.  So you will use the password admin to log in, but admin hashes to this string, which is stored in the database:
               0DPiKuNIrrVmD8IUCuw1hQxNqZc=                         [the equals sign should be at the end]
  3. Start up TMAJ, and then click the Login button.  Type in your username, and for the password, type in:
    admin
Note: If there are no records in the Users table, you must INSERT a new one.  After you insert a record, you can log on to TMAJ to create as many users as you want.


12) TMAJ can't connect to the database.  What's wrong?


TMAJ will give an error message that looks like:

edu.jhu.tmaj.servlet.request.impl.LoginRequest failed: java.sql.SQLException: SQL statement failed.  SQL = null exception: java.sql.SQLException: Server could not establish connection to database.
SPECIFIC REASON FOR FAILURE:
Chained Warnings:
com.mysql.jdbc.CommunicationsException: Communications link failure due to underlying exception:

** BEGIN NESTED EXCEPTION **

java.net.SocketException
MESSAGE: java.net.ConnectException: Connection refused: connect

STACKTRACE:

java.net.SocketException: java.net.ConnectException: Connection refused: connect
    at com.mysql.jdbc.StandardSocketFactory.connect(StandardSocketFactory.java:156)
    at com.mysql.jdbc.MysqlIO.<init>(MysqlIO.java:284)
    at com.mysql.jdbc.Connection.createNewIO(Connection.java:2565)
    at com.mysql.jdbc.Connection.<init>(Connection.java:1485)
    at com.mysql.jdbc.NonRegisteringDriver.connect(NonRegisteringDriver.java:266)
    at java.sql.DriverManager.getConnection(Unknown Source)
    at java.sql.DriverManager.getConnection(Unknown Source)
    at edu.jhu.tmaj.database.conn.AbstractConnectionFactory.getNewConnection(AbstractConnectionFactory.java:65)
    at edu.jhu.tmaj.database.conn.PooledConnectionManager.addNewConnection(PooledConnectionManager.java:171)
    at edu.jhu.tmaj.database.conn.PooledConnectionManager.getConnection(PooledConnectionManager.java:108)
    at edu.jhu.tmaj.database.DatabaseQuery.execute(DatabaseQuery.java:106)
    at edu.jhu.tmaj.beans.UserBean.lookup(UserBean.java:276)
    at edu.jhu.tmaj.servlet.request.BaseRequest.executeCommand(BaseRequest.java:67)
    at edu.jhu.tmaj.servlet.CommandServlet.doPost(CommandServlet.java:77)
    at javax.servlet.http.HttpServlet.service(HttpServlet.java:710)
    at javax.servlet.http.HttpServlet.service(HttpServlet.java:803)
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:290)
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:206)
    at org.apache.catalina.core.StandardWrapperValve.invoke(StandardWrapperValve.java:233)
    at org.apache.catalina.core.StandardContextValve.invoke(StandardContextValve.java:175)
    at org.apache.catalina.core.StandardHostValve.invoke(StandardHostValve.java:128)
    at org.apache.catalina.valves.ErrorReportValve.invoke(ErrorReportValve.java:102)
    at org.apache.catalina.core.StandardEngineValve.invoke(StandardEngineValve.java:109)
    at org.apache.catalina.connector.CoyoteAdapter.service(CoyoteAdapter.java:263)
    at org.apache.coyote.http11.Http11Processor.process(Http11Processor.java:844)
    at org.apache.coyote.http11.Http11Protocol$Http11ConnectionHandler.process(Http11Protocol.java:584)
    at org.apache.tomcat.util.net.JIoEndpoint$Worker.run(JIoEndpoint.java:447)
    at java.lang.Thread.run(Unknown Source)

** END NESTED EXCEPTION **

Last packet sent to the server was 16 ms ago.

  DATABASE SETTINGS:
  Database Connection String: jdbc:mysql://127.0.0.1:3306/tmaj
  Database Username: root
  Database Password: *****  [masked for security reasons]
  JDBC Driver: com.mysql.jdbc.Driver
  TROUBLESHOOTING:
  URL for more details on this error message:
  http://tmaj.pathology.jhmi.edu/doc/manual/FAQs.html#DATABASE_TROUBLESHOOTING 


Note the 'Specific Reason for failure:' that TMAJ gives, and locate your problem below.

 'Connection refused: connect' error message

If you get a 'Connection refused: connect' error, it means the server failed to make any kind of contact with the database.
You should try the 'telnet test' to see if you can make a connection.


    The Telnet Test
  1. On whichever machine is running Tomcat, run this command:
         telnet 127.0.0.1 3306
         [we get the actual IP address and port number from the connection string given in the error message]
  2. Note the message telnet prints.  If you got this error message, the telnet test should fail and you should get an explicit 'Connect failed' error.  This means the problem is outside of TMAJ. The network simply can NOT access the database using this IP address and port number.
    Possible reasons for 'Connection refused: connect' message:
  1. The database has been shut down. This is most often the case.
  2. A firewall is blocking your connection.
  3. You are using the wrong IP address or port number to connect to the database.     If this is the case, follow the directions below to change your database.properties file.

 'Invalid user ID or password' error message

 If you get this message, it simply means you supplied the wrong username and password to the database in the database.properties file. 
Follow the instructions below to change your database.properties file.  If you're using MySQL 4.0, the error message would probably include something like:
java.sql.SQLException: Access denied for user 'tmaj_user'@'localhost' (using password: YES)

 'JDBC Driver Class Not Found' error message

 If you get this message, it means the JDBC driver could not be found.
 The server must have access to the jar file with the JDBC driver.

 'Too Many Connections' error message

 If you get this message, you should know that TMAJ imposes a limit on how many connections are allowed to a database in:
     PooledConnectionManager.java.
 The database also imposes a limit.
 Check the database documentation on how to change this.
 You may be out of connections because of a programmer error,
 meaning the programmer forgot to return the connection after using it.
 Or it may be the case that simply too many users tried to connect to TMAJ at once.

Other Problems

1) You used an old JDBC driver to connect to the database.
   Check that the version of the JDBC driver matches the version of the database.
2) You used the wrong JDBC driver to connect to the database. This may have been
   done if you specified the wrong Database Type when using the API.

Changing your database.properties file:

 Parameters used to connect to the database are found in:
     config/database.properties
After altering this file, you must do run the command "ant push" to change the live version of tmaj.


13) How do I fix a "java.sql.SQLException: ORA-01861: literal does not match format string" error?

This error is seen on Oracle databases.  You probably have the wrong value for the NLS_DATE_FORMAT parameter.
You can find out your current value by running this command:
select * from V$NLS_PARAMETERS;

The value that a TMAJ Oracle database uses is: YYYY-MM-DD HH24:MI:SS

You can change this value by running this command:
alter system set NLS_DATE_FORMAT='YYYY-MM-DD HH24:MI:SS'

If this command doesn't work, you can try editing init.ora and restarting the database.


14) Do I need to install the "Apache Tomcat Native library which allows optimal performance"?

No.

You may see an warning in your Tomcat log files that says:
The Apache Tomcat Native library which allows optimal performance in production environments was not found on the java.library.path: ...

This message may be ignored for most environments, especially development and demo environments.
We have found that the performance of TMAJ is fine without installing this. 
However, if you do want to install it, go here: http://apr.apache.org/.

15) How do I create My Own Key to Sign a Jar File?


The keytool program is part of the JDK.

Run the following command to create a keystore and a java key:
keytool -keystore my.keystore -storepass tmaj123  -genkey -alias tmaj -keypass tmaj123 -dname "cn=John Smith, ou=DeMarzo Lab, o=Johns Hopkins University, st=MD, c=US"

You should replace the information in the -dname argument to your personal information.
For additional security, you should leave out the -keypass myPassword option and allow the program to prompt you for it.

One source of confusion is 2 passwords in the keystore.  Here is the difference.  The keystore is actually a collection of keys.  It may have one or more keys.  The keystore (collection of keys) has a password, and each additional key has a password.  The -storepass option represents the password for the entire keystore, and the -keypass represents the password for one of the keys in the keystore.
For simplicity's sake, it is recommended the password be the same.  This way, any time you have to do anything with one of the keys, you only have to enter 1 password.

Note: Any jar files you deploy over the web must be signed with a key.   If you used the steps above to create a key, Java Web Start will display a message urging the user NOT to run the application because in fact anyone could do the above steps, and say they are anyone.  To actually get Java Web Start not to display a warning message, you would have to contact Verisign or some other Certificate Authority and pay them a fee to create a key for you.

16) How do I upgrade TMAJ?

  1. First, perform appropriate backups. This will ensure you have a point to which you can return if something goes wrong.
    1. Backup TMAJ database before you start. 
    2. You should also backup the image files.
    3. Backup your TMAJ application before you start.  Zip up the tomcat/webapps/tmaj directory and save the zip file somewhere, then just delete that directory. That would make it a lot easier if you ever wanted to return to your old version of TMAJ.  Of course, you can always just use the original zip file you downloaded when you installed the old version of TMAJ.  You may also want to backup the files under Apache like the tmaj.jar file.  In theory, backing up the TMAJ application isn't as important because you should be able to recreate it all by using the old tmaj download zip file.  But backing up the TMAJ database (and image files) is really important, because those can't be recreated.
  2. Get the latest TMAJ installation zip file.  This will be available on source forge.
  3. Unzip the installation files in any directory.
  4. Know the version number of your old TMAJ installation.
  5. Update your database schema using the database_updates.sql file in the zip file you downloaded.  You will not need to run all of these, so you should check the dates and version numbers of the upgrading SQL scripts.  Also note that these scripts are made for a Sybase database, so you may need to convert them to Oracle.
  6. Re-do the "Setup the Config Directory" step described on the TMAJ server setup page. 
  7. Re-do the "Deploy Application" step described on the TMAJ server setup page. 

17) Why isn't Tomcat finding a URL?

One common mistake is people typing the wrong case.  Tomcat is case-sensitive.

18) Why doesn't Tomcat reflect the changes I made in the source code?

You must do a reload for tomcat to see your changes.  If you are using ant, this is being done for you.  You would probably only run into this problem if you were trying to copy the files yourself, or doing an 'ant gui' without first doing an 'ant reload'.

19) Why does my JNLP file come up as text instead of launching Java Web Start?

There are 2 possible reasons.  One is that the client has .jnlp files associated with a text file.  To fix this simply right click on a .jnlp file, choose "open with" and then choose Java Web Start, and check the "Always use the selected program to open this kind of file".

The other reason is you forgot to setup a mime type.  Tomcat should already have this setup.  If you are using Apache HTTP Server, do this:
Go into the mime.types and add this line:
        application/x-java-jnlp-file    jnlp      [there is a tab between the two]

20) What IDE is used to develope TMAJ?

Eclipse is used.

21) What does this error mean: "java.net.ConnectException: Connection refused: connect"?

It means that whatever Java is trying to connect isn't running, or there is a firewall problem.  It means basically that the client is making NO contact with the server. You might see this message when using Ant when Ant tries to connect to Tomcat.  This message may also be seen when the program is trying to connect to the database.  You should check if Tomcat is running.  You should also try the "Telnet Test" described earlier in this document.

22) How do I backup my data in TMAJ?

It is very important to make regular daily backups of the data in TMAJ.
To backup the data in TMAJ, you must not only backup the database, but also the image files, which are stored outside of the database.
TMAJ stores a link to the image files in the database.

23) How do I backup my TMAJ installation?

In this question, we are NOT referring to the data in TMAJ, that is, your own custom data that is entered through the GUI or the images files.  Rather, we are referring to backing up the TMAJ application.  To backup the TMAJ installation, the fastest way is just to backup the zip file that you downloaded to install TMAJ.  It will have a name such as: tmaj_2.34.0.zip.  You will lose your configuration information in the config files but you can always re-type it in.

24) Does TMAJ have any database triggers?

No.  For example, in doing an auto-increment for Oracle, nextval is called explicitly. 


25) Why is Tomcat unable to read files on the network drive?

This is perhaps because you are running the Tomcat service as the wrong user. 
Open "Windows Services", and then locate the "Apache Tomcat" service.
If you are running Windows, do NOT specify Tomcat to log on as a "Local System account".
Instead, choose the "This Account" radio button and then specify an authorized user that can access the needed network resource.  As an alternative, you can enter a local system account that has the same username and password of a user on the server that has the needed access.

26) Why do I get the error: java.lang.IncompatibleClassChangeError: Found class com.sun.image.codec.jpeg.JPEGImageEncoder, but interface was expected?

You probably received this error while importing images on a linux system such as Ubuntu.  This is due to using an alternative JDK such as OpenJDK.  Uninstalling the OpenJDK should solve this problem.  Make sure that you have Sun's JDK installed.


<< Back to the Manual


© Copyright 2009 | All Rights Reserved | The Johns Hopkins University