## Frequently asked questions

1. Why doesn't Example.java work?
2. Why do I get an "unkown database" exception?Is it possible to fetch all feature_ids for features (e.g. genes) overlapping a location?
3. I think I've found a bug in ensj, or at least I am getting stack traces from it, what should I do?
4. How do I report a bug?
5. Why is the data returned via ensj different to what I see on the web site?
6. What version of the ensj am I running?
7. How can I get the source code corresponding to a particular build (release or snapshot)?
8. Can I distribute ensj.jar or ensj-XX.X.jar with my application?
9. Can I distribute mysql-connector-java-XXXXXX.jar with my application?
10. Can I connect to ensembl data stored in MS SQL or Sybase servers?
11. What does the exception "Connection pool limit of XXX exceeded" mean and what can I do about it?
12. Why do I (sometimes) get a connection refused exception when I try and retrieve data from ensembldb.ensembl.org?
13. How can I get all the putative orthologues for a gene?
14. I'm having trouble connecting to the database via JDBC, how can I fix it?

1. Why doesn't Example.java work?

   This is usually caused by the Example program trying to connect to a database that has been removed from the mysql server ensembldb.ensembl.org:3306. This bug only happens in old version of ensj and upgrading to the latest build of ensj.jar will fix this problem.

2. Why do I get an "unkown database" exception?

   This means that the database is not available on the database server. Perhaps the database name is misspelt or the database has been removed. This sometimes happens if you are using an old configuration file that refers to an obsolete database. A list of current databases on ensembldb.ensembl.org is available in the file ensembldb.ensembl.org-databases.txt in the latest build.

3. Is it possible to fetch all feature_ids for features (e.g. genes) overlapping a location? Yes, you can use the `fetchInternalIDs(Location)` methods but you might want to consider using the `fetchIterator(Location)` methods instead. These provide a very simple interface with a fast implementation that uses relatively little memory even for whole genome queries. Examples:
   - `long[] ids = geneAdaptor.fetchInternalIDs(location);`
   - `Iterator iter = geneAdaptor.fetchIterator(location);`
4. I think I've found a bug in ensj, or at least I am getting stack traces from it, what should I do?

   It is possible that your bug has been fixed or is due to an incompatiblity between the versions of ensj.jar, mysql.jar (MySQL JDBC driver) or the MySQL database you are using. The first thing to do therefore is to make sure you are using the right jars. You can download the latest ensj release and a compatible mysql driver from the download section. Note that some users have experienced problems with both older and, surprisingly, newer mysql.jars so ensuring you are using the version we distribute is an important step in the debugging process.

   Secondly, several people have experienced problems using ensj that were caused by referencing old ensj-XX.Y or mysql-XXX jars in their CLASSPATH.

   - Running your program like this should resolve the problem: `java -cp ensj-XX.Y.jar:mysql-XXX.jar:$CLASSPATH some.package.YourClass`.
   - Add `System.out.println(SystemUtil.environmentDump())` to the beginning of your program to discover which jars the ensj and mysql classes are being loaded from. If the program won't compile or run after adding this line because of a "SystemUtil.environmentDump() is missing" error then you are using an old ensj-XX.Y.jar.

   If the bug occurs when you use the latest ensj-XX.Y.jar and mysql-ZZZ.jar then you should submit a bug report.

5. How do I report a bug?

   To begin with, read the "I think I've found a bug in ensj" section. Once you are convinced it is a real bug in ensj you should include these items in a bug report:

   - A test class with a main() method that demostrates the bug. Include `System.out.println(SystemUtil.environmentDump())` as the first line of main() which will generate additional debugging information.
   - The output generated by the test program running including all stack traces.
6. Why is the data returned via ensj different to what I see on the web site?

   This is usually because the ensj driver is pointing at a different database to the website. Configuring the driver to point at the same database as the website (the latest) usually solves this problem.

7. What version of the ensj am I running?

   It should be in the jar name but if not you can also run this command to find out: `prompt>java org.ensembl.util.Version`.

8. How can I get the source code corresponding to a particular build (release or snapshot)?

   The source code for the latest release is included in the latest distribution. Other versions of the source code corresponding to other builds are available from CVS using the appropriatte tag. For example, after checking out ensj-core ,`cvs up -r release-ensembl-25-0` would retrieve all the files in the 25.0 build (release or snapshot).

9. Can I distribute ensj-XY.Z.jar with my application?

   Yes. Ensj is published under the LGPL so you can redistribute the jar although you should also include a copy of the LGPL. For instance copy LICENSE to LICENSE-ensj in the same directory as your own license.

10. Can I distribute mysql-connector-java-XXXXXX.jar with my application?

    This question should really be answered by reading the MySQL AB license. It took me a little time to read through this so I'll give my short interpretation of it here on the grounds that it might save you some time. This interpretation might be wrong and comes with no warranty so you should still read the original for yourself. Enough caveats, here's my take on the license situation:

    - If your program is GPL you can distribute the jar.
    - If you have another open source license you might be able to distribute it. See open source license exceptions for a list of "compatible" open source licenses.
    - If you have a non open source license, e.g. commercial, you probably need to buy a license in order to redistribute the jar. Alternatively your end users could download the jar themselves from the MySQLConnector J section of the MySQL download page.
11. Can I connect to ensembl data stored in MS SQL or Sybase servers?

    Probably. Ensj has been partially tested against an MS SQL database loaded with ensembl data via the jDTS jdbc driver (http://jtds.sourceforge.net). Sample configuration properties to put in the ensembl driver config file:

        connection_string=jdbc:jtds:sqlserver://HOST:PORT
        jdbc_driver=net.sourceforge.jtds.jdbc.Driver

12. What does the exception "Connection pool limit of XXX exceeded" mean and what can I do about it?

    This means that your EnsemblDrivers are attemping to open too many database connections. Each driver gets it connections from a connection pool which is either unique to it or shared between several drivers. The drivers returned from Registry.createDefaultRegistry(), for example, all share a common pool of connections for accessing the databases on the ensembldb MySQL server.

    Options to overcome this problem:
    - Reduce the number of concurrent queries/open connections your program uses.
    - Increase the connection limit (<=32 for ensembdb). One way to do this is to create a registry with the new connection pool limit. (requires >= ensj-35.1):
      - create a new config file:

            # ensembldb.ini
            [default]
            host ensembldb.ensembl.org
            port 3306
            user anonymous
            min_version 20
            connection_pool_size 20
            type species

      - create a new registry using the config file (requires >= ensj-35.1.jar):

            Registry r = new Registry(RegistryLoaderIni(new String[]{"ensembldb.ini"}, new ServerDriverFactory(), true));

13. Why do I (sometimes) get a "connection refused" exception when I try and retrieve data from ensembldb.ensembl.org?

    This happens because too many connection requests have been made from your IP address. Ensembl's MySQL server ensembldb.ensembl.org:3306 only allows 32 connections per IP address. Note that if several users connect to the database from behind a NAT firewall they all appear to have the same IP address.

14. How can I get all the putative orthologues for a gene?

    Putative orthologues generated by recipricol BLAST hits are stored in the compara database and can be retrieved via a ComparaDriver. This example shows how to print all the orthologues for the human gene `ENSG00000118961` from the latest ensembl databases. ``

            ComparaDriver compara = Registry.createDefaultUserRegistry().getGroup("compara").getComparaDriver();

            List gdbs = compara.getGenomeDBAdaptor().fetch();
            for (int i = 0; i < gds.size(); i++) {
              GenomeDB gdb =(GenomeDB) gdbs.get(i);
              String targetSpecies = (String) gdb.getName();
              // if we were only interested in hits in chicken...
              // List hits = compara.getMemberAdaptor().fetch("Homo sapiens", new String[]{"ENSG00000118961"}, "Gallus gallus");
              List hits = compara.getMemberAdaptor().fetch("Homo sapiens", new String[]{"ENSG00000118961"}, targetSpecies);
              System.out.print(targetSpecies);
              for (int j = 0; j < hits.size(); j++) {
                FeaturePair p = (FeaturePair) hits.get(j);
        	// hitDisplayName is the orthologue gene name; begins with
        	// "ENS" if ensembl predicted gene otherwise name is assigned
        	// by another group.
                System.out.print("\t" +p.getHitDisplayName());
              }
              System.out.println();
            }

    Here is similar code in jython: `

            genomes = ensembl.ensembl_compara.genomeDBAdaptor.fetch()
            for speciesName in [g.name for g in genomes]:
                orthologues = ensembl.ensembl_compara.memberAdaptor.fetch("Homo Sapiens", ["ENSG00000118961"], speciesName)
                geneNames = [o.hitDisplayName for o in orthologues]
                print geneNames

    `
15. I'm having trouble connecting to the database via JDBC, how can I fix it?

    There are obviously many possible causes but a non-obvious one I've recently encountered causes the following entries in the stacktrace

        java.net.SocketException: Invalid argument or cannot assign requested address

    The problem was particularly strange because I could connect to the database via the standard (mysql) client program.

    The problem was caused by SELinux on fedora core and I found two solutions:
    1. Ensure SELinux is configured correctly to allow JDBC connections. I can achieve this on my system by configuring it like this: It is enabled, enforcing and targeted.
    2. Turn SELinux off. Obviously this isn't a very good solution if you desire SELinux security.
    If you know of another solution please let us know.