		Bugzero Frequently Asked Questions

General Questions:

Q: What are the system requirements?
A: Bugzero utilizes your existing hardware and software, and can be integrated seamlessly
   with your current Java/J2EE and database systems. The server is cross-platform and can be 
   installed on (with exactly the same code base):
     Windows including NT, 2000, XP, 2003 server, etc.
     Linux,
     Unix,
     IBM iSeries (AS/400),
     Mac OS operating systems.

   The server requires:
     1. J2SE (JDK 1.3+)
     2. A Java Servlet engine or J2EE application server.
     3. A database.
     4  A SMTP mail account (optional).

   Bugzero has to be installed on the same computer where the Servlet engine
   and JDK is installed. On the other hand, the database and SMTP server can be
   anywhere (either on the same computer or not).

   Bugzero is web-based, and so for end users, only a browser is required.

Q: What are the supported database systems?
A: Theoretically, Bugzero should run on all the available database systems.
   Bugzero has been tested and deployed in production environment on MySQL 3.23+,
   PostgreSql 7.1, Access 97/2000, SQL Server 7/2000/2005, Oracle 8i/9i, IBM DB2 7.2,
   IBM DB2 on AS 400, and Sybase ASE 12.0.

   If you use IBM iSeries (IBM AS/400) DB2, you have to enable journaling for
   the database. You can do that with CRTJRNRCV (Create Journal Receiver),
   CRTJRN (Create Journal), and STRJRNPF (Start Journal Physical File).

Q: What are the supported J2EE or servlet containers?
A: Theoretically, Bugzero should run on all the available J2EE or Servlet engines.
   Bugzero has been tested and deployed in production environment on 
   Tomcat 3.x, 4.x, and 5.x, JBoss 2.x and 3.0, WebLogic 6.x and 7.0, WebSphere 4.x and 5.0,
   Oracle 9iAS, iPlanet Web Server 6.0 and Application Server 6.5 (SunOne),
   Orion Server 1.5.2, JRun 4, Resin 2.1.4, and 
   Novell exteNd Application Server 5.0 (SilverStream).
   
   Bugzero needs only a servlet container, an EJB container is not required.

Q: What are the supported Web browsers?
A: Bugzero does not use Java Applet, Microsoft ActiveX, or any other Plugins.
   Bugzero does need Javascript. It has been tested on the following browsers:
   IE 5.x, 6.x, 7, Mozilla 1.x, Firefox, Netscape 4.7+, 7,
   Opera 6.0+, Apple Safari 1.x, and Konqueror. 
   Other browsers should also work, but they have not been officially tested.

   Please note that, when attaching a file, if the browser encoded the multipart
   form data incorrectly, Bugzero will reject the data and you will see an error
   message. This may occur for the following browsers:

     MSIE 5.01; Windows NT 5.0
     Konqueror/3; Linux
     Konqueror/3.0.0-10; Linux

   The following problems have been reported, but normally they cannot be
   reproduced and they may never happen to you:

     With Netscape 4.79 on Solaris, the attachment page and the reports result
     pages do not display correctly. Version 7.0 apparently works fine. 

     With Netscape 7.0, the graphic reports cannot be displayed if the Cache
     property is set to "Every time I view the page", set it to "When the page
     is out of date" solves the problem.

     With IE6, if the Bugzero host computer does not have a DOMAIN (i.e.,
     WORKGROUP setup), then you may need use its IP address, instead of the
     hostname, in the url.  Otherwise, IE6 may not allow cookies.

   Also note that, for the Screenshot capture add-on feature, Java applet is required.

Q: Where to get the SQL Server 2000/2005 JDBC driver?
A: Because of licensing issues, we cannot package the driver. However, you 
   can download it free from <a href="http://www.microsoft.com/sql/downloads/">www.microsoft.com</a>.

   Install it to any directory and find out where the jar file sqljdbc.jar is located.
   During Bugzero's setup process, it will ask you where this file is, and the setup
   program will copy it to Bugzero's lib folder.

   Alternatively, since all you need is the jar file, you can just download the unix/linux
   version and unzip the file to get the sqljdbc.jar.

   Please note that, this driver also works with SQL Server 2000.

   Also note that, there a few other free or commercial SQL Server JDBC drivers available.
   If you want to use these alternative drivers, you will need edit db.properties
   and modify the driver name in the file (before running the Bugzero setup program).

Q: Where to get the Oracle JDBC driver?
A: Oracle JDBC driver comes with Oracle, the file is classes12.zip for Oracle 8i
   and ojdbc14.jar for Oracle 9i (and JDK 1.4). You can also download the drivers
   from the oracle website. Please note that, for oracle 8.16 or ealier, you must
   download a updated version of classes12.zip. The ojdbc14.jar driver works
   only for JDK1.4 or later.

Q: What jdbc driver should I use for DB2?
A: The DB2 driver comes with the database, the file is db2java.zip under the
   folder /SQLLIB/java. 
   Note that, even if the database is on the same local machine, it is better
   to use COM.ibm.db2.jdbc.net.DB2Driver, not COM.ibm.db2.jdbc.app.DB2Driver 
   The url is jdbc:db2://database_hostname/bugzero_db, where database_hostname
   can be localhost.

Q: Can Bugzero be installed in a virtual host environment?
A: Yes. Bugzero is completely self-contained and can be installed in a virtual host
   environment within a hosting company that supports Java servlet/jsp and database
   access. You may want manually configure the database properties and upload the
   entire bugzero package to your virtual host's application directory. You need
   then run 'bugzero -admin passwd' to create the base tables. 

Q: Can I run Tomcat as an NT service for Bugzero (on windows)?
A: Yes, you can. Bugzero is now completely self contained and does not
   require any modifications of the classpath. So, to Bugzero, there is no
   difference whether you launch tomcat with the NT service or with the command.

Q: What is the HTTP port number of my application server?
A: The HTTP port number of an application server is configurable. Below is the 
   default HTTP port numbers of some application servers:
     Tomcat (JBoss): 8080 (see server.xml)
     WebLogic: 7001 (see config.xml)
     WebSphere: 9080 (server-cfg.xml)
     Oracle 9iAS: 8888 (see default-web-site.xml)
     iPlanet: 80 (see server.xml)
     Orion Server: 80 (see default-web-site.xml)
     JRun: admin (8000), default (8100), samples (8200) (see jrun.xml) 
     Resin: 8080 (see resin.conf)

Q: How to deploy Bugzero on IBM WebSphere 4/5?
A: You can deploy Bugzero with the WebSphere administration console. 
   First, cd to the bugzero directory and type 'jar ../bugzero.war .'.
   And then move the resulted bugzero.war to WebSphere's installableApps
   directory and use the administration console to deploy bugzero.war.
   
Feature Related:

Q: How can I add more user groups?
A: You can add/remove groups by using the GROUP administration page.
   Note that, groups admin and guest are preloaded. 

Q: Can Bugzero cc email to people?
A: Yes, there is a cc email field on the create and edit bug page. One can cc multiple
   people. The email addresses should be seperated with ";".

Q: The hype-link in the bug notification email does not work.
A: The default email template is created based on the file /data/template/email_body.
   You need modify the template by replacing 'http://localhost:8080' to the real url 
   for each project using the EMAIL adminstration page.

Q: How can I always send notification email to the original submitter?
A: There are two flags, 
   system.jsp.notifyOriginalAuthor and system.email.notifyOriginalAuthor,
   you can set one or both of them to true in system.properties.
   You need restart your application server after the change.

Q: I do not have a smtp mail server, can I disable sending email?
A: Yes, you can disable Bugzero sending email by setting (in the file mail.properties):
   mail.mailer.disabled=true

   Please note that, by default, email notification is enabled and if you do not either
   disable it or set up the mail account, you will notice some exceptions in the log
   file. 

Q: Can I change the project name of an existing project?
A: Yes. The project name that is actually seen by the end users is now different from
   the project ID. While the ID of an existing project can not be changed, the name can
   be changed at runtime by using the administration interface. The change will be seen
   immediately to the end users.

Q: Does Bugzero accept bug reports submitted through email?
A: Yes. Bugzero has an advanced parsing capability for inbound emails. Email bug 
   submission can either modify an existing bug(s) or create a new bug. It has
   a spam-filter and can also handle email attachment. 

Q: Can Bugzero be integrated with CVS source control system? 
A: Yes. Bugzero can be integrated with CVS version control system through our email API.
   You need configure your CVS such that the loginfo will be sent to an email address set
   up for this purpose. Detail instruction is available under WEB-INF/misc/email/.

Q: Can Bugzero be integrated with Perforce? 
A: Yes. Bugzero can be integrated with Perforce through the email API.
   You need run the Change Review Maemon on the p4 server, and create a p4 user
   for the project you want receive email. You need add the dir/files in this user's
   Review.

Q: Does Bugzero support internationalization?
A: Yes, internationalization is now fully supported for Servlet 2.3 containers and
   databases that either directly support UTF-8 character set or their JDBC driver
   can encode the unicode in the front.

   Bugzero with UFT8 has been tested on Oracle 8i databases with UTF8 character set,
   and on MySQL 3.23 with the jdbc driver useUnicode set to true.    
   MySQL 4.1.1, yet to be released, shall support UTF8 character set directly. 
 
   If you use Asian languages such as Chinese, Japanese, and Korea, you may
   consider using UTF8, that can be switched on with system.charset=UTF-8 in the
   file system.properties.

   If you do not have a proper database that supports UTF, then you should not
   use UTF setting. Bugzero still works fine on the browser by saving the data in
   unicode numbers and displaying the characters correctly. In the email notification,
   however, mail clients such like outlook will show undesirably the unicode numbers,
   not the corresponding characters.


Runtime Errors:

Q: The graphic report failed to be displayed and exceptions occurred.
A: On Linux or Unix OS, an exception is thrown by the Java AWT toolkit when it
   can not make a connection to an X11 server. The exception can be something like
   "Can't connect to X11 window server using ':0.0' as the value of the DISPLAY variable".
   
   If your OS has graphics support, you need make sure that the local X11 is running,
   and the DISPLAY variable is correctly set. 

   If you are on a unix server that does not provide a graphical user environment,
   there are three alternatives:

   1. Sun JDK 1.4 Headless mode
      If you are using JDK 1.4, then you can use the Headless graphics mode to launch 
      the server, ie, you can add a java argument of -Djava.awt.headless=true.
      For example, with Tomcat, add the following line in cataline.sh (or setclasspath.sh):

      JAVA_OPTS=-Djava.awt.headless=true

      Note that, it seems the presense of X11 runtime libraries is still needed, that
      is, an X11 environment must be installed into the system, but the X11 server 
      itself need not be started. For example, for RedHat Linux, the minimum set
      of X11 packages needed is:
        * XFree86
        * XFree86-libs

   2. Virtual X11 Frame Buffer (Xvfb)
      For JDK 1.3, the headless mode is not available. If you do not have X11 sever,
      you can install a lightweight Xvfb (XFree86-Xvfb package).
      In your server launch script (such as tomcat.sh), add the following lines:

       if [ -f /usr/X11R6/bin/Xvfb ]; then
          /usr/X11R6/bin/Xvfb :1 -screen 0 1x1x8 > /dev/null 2>&1 &
       fi
       export DISPLAY=:1.0

   3. Pure Java AWT (PJA) 
      Another alternative is PJA. For more detail and to download the software, go to
      http://www.eteks.com/pja/en/. 

Q: After I login, it takes me to the same page, what is going on?
A: Bugzero uses session to store temporary data, you need enable 
   'Allow per-session cookies (not stored)' for Bugzero to work.
     For IE5, the Cookies section is under 
            Tools menu - Internet Options - Security - Custom Level.
     For IE6, it is under 
            Tools menu - Internet Options - Privacy
     For Netscape, it is under
            Edit - Preferences - Advanced
     For Mozilla, it is under
            Edit - Preferences - Privacy & Security - Cookies

   Note that, for later versions of Bugzero, it should explicitly inform you so.

Q: When I switch project, it always fall back to the HOME page and display the
   bug list of the previous project.
A: This is a browser caching problem, check your browser's caching status.
   For IE 5.5 or later: Tools - Internet Options - General - 
                Temporary Internet files - Settings
                and select "Automatically" or "Every visit to the page"
   
   For Netscape Versions 4 or later or Mozilla 1.x: 
                Edit - Preferences - Advanced - Cache,
                and select "When the page is out of date" or 
                           "Every time ...".

Q: What is this COM.ibm.db2.jdbc.DB2Exception?
   [IBM][JDBC Driver] CLI0616E  Error opening socket. SQLSTATE=08S01
A: This happens if the DB2 JDBC Applet Server is not running. You need start
   this service.

Q: What is this COM.ibm.db2.jdbc.DB2Exception?
   [IBM][JDBC Driver] CLI0637E  QUERY cannot be found
A: This is a known bug in the JDBC driver in DB2 PF5, it occurs when a SQL
   statement contains TAB or new-line characters. You need upgrade the
   JDBC driver.

Q: With MySQL, when attaching a file, I got 
   java.lang.IllegalArgumentException:
   Packet is larger than max_allowed_packet from server configuration of 1048576 bytes
A: This happens when the file you are trying to attach has a size larger than the 
   max packet size of your mysql server (the default is 1M). To solve this problem,
   in mysql's configuration file (my.cnf), under [mysqld], add   
   set-variable  = max_allowed_packet=12M 

   Note that, after the modification, you need restart mysqld as well as your
   servlet engine.

Q: Sybase, error when creating tables:
   The column default_project in table person does not allow null values.
A: With Sybase, by default, it may not allow null values in string columns 
   (like VARCHAR, TEXT, etc). In that case, you will have the above error. The
   solution is to change this default value for a database using "isql" by issuing
   the following command:

   sp_dboption db_name, "allow nulls by default", true

   Here, "db_name" is your database name.

Q: Sybase, error when dropping tables:
   ... command not allowed within multi-statement transaction. 
A: If you encounter this error, issue the following commands at the Sybase command
   line:

   use db_name
   go
   sp_dboption db, "ddl in tran", true
   go

   Or, use "isql" to issue the following command:

   sp_dboption db_name, "ddl in tran", true

   Here, "db_name" is your database name.

Q: I am using Tomcat 4.1.14, when run Bugzero, sometimes I got a blank page.
   What happened?
A: This is an issue with Tomcat 4.1+ using the CoyoteConnector. The problem
   can be fixed by replacing CoyoteConnector to HttpConnector. Specifically, in
   tomcat's conf/server.xml file, you alter   
   
   &lt;Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
   ...
   to
   &lt;Connector className="org.apache.catalina.connector.http.HttpConnector"
   ...
   You need restart Tomcat for the change to take effect.

Q: Is there a potential zip file classloading problem with Tomcat?
A: Yes, if you add a zip file in the WEB-INF/lib folder, Tomcat may not load this zip
   file into the classpath. The problem can be solved by renaming the zip extention to
   jar (you do not need unzip and jar the file, just need rename it).

   The above could cause problems if you use Oracle or DB2 databases since both their
   jdbc drivers are packaged into a zip file. If such a problem occurs, please rename
   classes12.zip to classes12.jar or db2java.zip to db2java.jar.

Q: With Tomcat, when login, I got an error: 
   Unable to compile class for JSP ... package com.websina.bean does not exist

A: This is probably caused by a bug in certain Tomcat versions. It seems that,
   when there is a blank space the directory path where Tomcat is installed, 
   the jsp compiler cannot find the java classes under the WEB-INF/lib.

   When you install tomcat on windows, the default directory path is 
   C:\Program Files\Apache Group\tomcat_xxx,  you should change it to, 
   C:\tomcat_xxx instead.

   Another possible solution is to move bugzero.jar under bugzero\WEB-INF\lib
   to tomcat's common\lib directory. That also seems solve the problem.

Q: When login, I got the following exception (Unix file permission):
   java.lang.NoClassDefFoundError
   at com.websina.bean.Person.login(Person.java)
A: This is a very misleading error. The real cause of this is the log file 
   bugzero.log is not writable (.../bugzero/WEB-INF/classes/log/bugzero.log).
   This happens only on Unix/Linux OS where the owner of the application server
   process is different from the log file owner. You need make this file writable to
   this process owner and probably restart server.

   Before you get this error, when you first time log on to Bugzero from the
   browser, you should get something like:
   java.lang.ExceptionInInitializerError: java.lang.RuntimeException: 
   .....log/bugzero.log (Access is denied)
   at com.websina.util.log.Log.(Log.java) .....

   and subsequent login results NoClassDefFoundError. 

Q: When login, I got
   Cannot create connection pool, check log for detail.
A: This will happen if the application server (or the servlet engine) can not
   find the JDBC driver and failed to create the connection pool. The driver
   jar file(s) should be automatically copied into bugzero/WEB-INF/lib during
   Bugzero setup. If they are indeed there, then, restart the server will solve
   the problem.

Q: When login, I got
   Failed to read sql file: login_person
A: In certain application servers and servlet engines, the ContextClassLoader
   is not implemented properly. And because of that, files in the WEB-INF/classes
   are not found. To solve this problem, you need edit the file system.properties
   (under WEB-INF/classes/conf) by setting system.data.dir to the directory path
   of bugzero/WEB-INF/classes (see inline comments in the file). After that, you
   need restart the server.

Q: Why email notification is not sent, and what are these JavaMail Exceptions?
   (SecurityException, NoSuchProviderException, NoClassDefFoundError)
A: Email notification is not sent because of these exceptions:
   javax.mail.NoSuchProviderException: smtp
   or
   javax.activation.UnsupportedDataTypeException: no object DCH for MIME type text/plain

   These error messages are produced by JavaMail and are completely misleading. 
   The root cause of the error is a mis-matched or a duplicate pair of mail.jar and
   activation.jar. Bugzero packaged mail.jar and activation.jar under WEB-INF/lib,
   and if your servlet engine have its own pair of jars in its common or shared lib,
   problem may arise. A simple solution is to remove one pair of mail.jar and
   activation.jar either from Bugzero's WEB-INF/lib directory, or from servlet engine's
   common/share lib directory. 

   You may also see 
     java.lang.SecurityException: Access to default session denied
   and/or subsequent
     java.lang.NoClassDefFoundError
   The cause of the error is the same as above, and so removing one pair of mail.jar
   and actovation.jar shall solve the problem.

Miscellaneous:

Q: Which PostgreSQL binary data type can Bugzero use? 
A: PostgreSQL has two binary data types, OID and bytea.
   By default, Bugzero uses PostgreSQL bytea for its binary columns. This works only
   for PostgreSQL 7.2 or later. For Version 7.1, you need modify the file db.properties
   by setting postgresql.LONGBINARY to OID instead of bytea.

Q: Can the Microsoft SQL Server 2000 JDBC driver be used on SQL Server 7?
A: The SQL Server 2000 JDBC driver downloaded from Microsoft supports only the
   SQL Server 2000. If you use it on the SQL Server 7, you will get something like:
   java.sql.SQLException: [Microsoft][SQLServer 2000 Driver for JDBC]This version of
   the JDBC driver only supports Microsoft SQL Server 2000.  You can either upgrade
   to SQL Server 2000 or possibly locate another version of the driver.

   If you cannot find a free JDBC driver for SQL Server 7, you can create a data source
   (DSN) that points to your SQL Server 7 and then use the jdbc-odbc driver for the
   DSN. But before you launch the Bugzero setup program, you need modify the file
   db.properties. See comments inside the file.

-------------------------------------------------
Bugzero homepage: http://www.websina.com/bugzero/
        Faqs: http://www.websina.com/bugzero/faq.html
For questions:    mailto: dev@websina.com
