Java Tutorial

Setting up a Project and Preparing to Scan Your Code

In this section, you will learn how to configure the Globalyzer Workbench so it can do a static analysis of the source code files. There are two main parts to this action:

  1. Configure how to access the source code
  2. Configure how to scan and fix the code

Note: an online video guide is available for this section of the tutorial. To see this video, as well as other Globalyzer video tutorials, click here. The video guide for this section of the tutorial is titled "Part One: Creating an Internationalization Project".

Access to the source code

Eclipse savvy users may skip this section and check out our tutorial SVN code from https://lingoport.svn.cvsdude.com/globalyzertutorial (devlingoport/lingoguest); for users new to the Eclipse project handling, we suggest three main ways to create a project and give access to your source code:

  • Pointing to a location if you already have your code on disk
  • Importing the source code into the Workbench workspace
    1. from the file system
    2. from a repository

    Before choosing a method and creating a project, please read those three alternatives. Then choose one way.

    • 1. Pointing to an existing location on disk

    Note: For this lesson, you need to download the sample Java code that will be used for the remainder of the tutorial.

    Click here to download the sample code.

    Save the zip file to a convenient location on your local system and then unzip it. In this tutorial, the files are un-zipped under C:\tmp\example-source-java.

    This method may be useful if you are working with files from an external system. Simply copy the files to your disk and create the project as specified below. (Note: If you want to modify the files and use SVN, CVS, Git or another source control system directly from the Globalyzer Workbench, this method is not the right choice for you. Please read through the section Checking out a Project from SVN that appears later on this page.)

    • Select File=>New=>Project... A new project wizard appears.


    • Choose creation of a Java project. Since we un-zipped the files under C:\tmp in this example, we enter C:\tmp\example-source-java as in the following screen:

    • Click Finish and then New to create an associated Globalyzer Project. You'll then see the Create Globalyzer Scan page. Click Cancel and then answer No to the Java perspective question so that you stay in the Globalyzer perspective. We'll be configuring Scans later on this this section. Before continuing with the creation of a scan, we propose two other ways to get your tutorial project.

    2. Importing source code into the Globalyzer Workbench workspace

    Note: If you choose to import from local files, first download the example java source code as indicated above. In our example, they are then located under C:\tmp\example-source-java. There are many ways to import source code into the workspace which is the typical Eclipse location for file editing.

    • Select File=>New=>Project... A new project wizard appears.

    • Choose creation of a Java project. This project will host the imported files later on. For the project name, give example-java-project. Check to determine whether the default location used correctly points to the location of the source on your machine. If it does not, uncheck Use default location and browse to the location of the source on your machine. Click Finish: A directory under the workspace is created.

    • You'll then see the Create Globalyzer Project page. Click New, the Manage Scan Wizard pops up. Click Cancel. Configuring Globalyzer scans will be addressed later in this section. A dialog will appear asking you if you want to switch to the Java perspective. Answer No to the Java perspective question so that you stay in the Globalyzer perspective. Before continuing with the creation of a scan, we propose one other way to get your tutorial project.

    3. Checking out a Project from SVN

    In the case where your files reside in source code control and are not part of your i18n environment, you may want to check them out using for instance CVS or SVN. CVS is part of the default distribution. We use SVN to illustrate also how to add functionality to the Globalyzer Workbench. If you already have SVN, skip to the checkout step.

    Adding the SVN plug-in

    Eclipse, hence the Globalyzer Workbench, uses plug-ins as an extension mechanism. A plug-in is a set of components that adds functionality to a software application. There are plug-ins to better handle tasks or to connect to defect tracking system or to better handle Web applications. The plug-in you are going to add is a Subversion plug-in to share code under SVN with your development team.

    Select Help=>Install new software... A wizard dialog box pops up.

    Copy and paste the following Subversive plug-in into the dropdown:
    http://download.eclipse.org/releases/indigo

    Select the Subversive items and continue installing with default settings. Restart the Globalyzer Workbench. On the next screen, choose the most up to date SVN Kit version. You may also want to select JavaHL, although this has been known to produce an error when installing the connectors. If the error occurs simply de-select JavaHL and try again.

    You will be warned that the svn connector software contains unsigned content. It is recommended that you proceed with the install despite this.

    Click OK.

    The SVN plug-in has been installed! You will need to restart the Globalyzer Workbench again before continuing.

    Checking out the code using the SVN plug-in

    With the SVN plug-in, you can get code under a simple repository to illustrate the capabilities of checking out, seeing what changes have been made compared to the checked out code, see the revision history and so on.

    There are a few ways to use the SVN plug-in. For instance, you could add an SVN repository view and create a repository location there or import using SVN. In this tutorial, you will use New Project and checkout from SVN.

    • Select File=>New=>Project... a dialog box pops up. Choose SVN/Project from SVN.

    • Create a new repository location using the username devlingoport, the password lingoguest and this URL: https://lingoport.svn.cvsdude.com/globalyzertutorial/GlobalyzerTutorialJava. Note: do not commit the changes you make.

    • Click Next.

    • Select Revision 15 to make sure you do have a working application.

    • Click Finish.

    • Set up as shown next, renaming project to example-source-java

    • Click Next.

    • For the purposes of this tutorial we will be placing the source at C:\tmp. To do this, please uncheck the option "Use default workspace location" then enter "C:\tmp" into the Location field.

    • Click Finish to check out the source code.

    • Once you have checked out the source code, a Select Globalyzer Project window may appear. If it does, skip to the next bullet point. Otherwise, find the associated project in the Project Explorer view (upper-left corner of the main window). Right click on it, then select Globalyzer=>Add/Remove Globalyzer Nature.

    • The Create Globalyzer Project window should now have appeared. Click new to create a Globalyzer Project. If you subsequently see the Create Globalyzer Scan page, click Cancel. We'll be configuring Scans later on this this section. If you are asked a Java perspective question, answer No. This will ensure that you stay in the Globalyzer perspective. Close any remaining dialogs.

    • The content of the Project Explorer view should now resemble the following:

    Checking Project Source

    Tip: Project Explorer is a fairly generic explorer which will work for different languages. For this Java project you may want to use Package Explorer which can be added to the perspective using Window=>Show View.

    1. Run the tutorial application. To do so, navigate to src/com.lingoport.demo.java in the Project Explorer view, right click on the ExampleMain.java file.

      Select Run As=>Java Application in the lower portion of the shortcut menu. The application should look like the start of an address book:

      Close the application. During the course of this tutorial, you will do some basic internationalization work for this simple application.


    2. Although with this simple tutorial it is not necessary to run the File Inspector, in a more complex application you will find it very helpful in scoping your internationalization effort. The File Inspector will group your source code files by programming language and suggest the types of Globalyzer Rule Sets you should create to scan the files.

      From the Menu bar, select Project=>Run Project Files Inspector....

      The File Inspector dialog displays:

    3. Take a moment to look at the fields. You set the Source Path to the base of your Source Code files and the Excel Output path to the file path of the generated Excel file. The File Extensions/Language Group list tells Globalyzer which source file extensions to count and group. For example, asp is a VB Classic file extension, whereas acsx, aspx and asax fall under the ASP .NET language group. You can add and delete entries using the Add Extension and Remove Extension buttons. To restore the list back to Globalyzer's default, click Restore Defaults. Click Add Extension:

    4. To add a new file extension to an existing group, use the exact same name in the Language Group field. To add a new group, fill in a new language group name. For this tutorial, we can use Globalyzer's default groups, so click Cancel.

    5. Fill in or browse to the location of your Java tutorial source code and enter Java_FileInspection.xls in the Output Excel field as shown below.

    6. Click Generate to create the Excel file.

    7. Open the Excel file outside of the Workbench.

      The Summary worksheet lists and counts files that are grouped in the File Inspector dialog box. It also lists the Rule Sets that you'll need to create in the Suggested Rule Set(s) column. As you can see, our simple tutorial has few Java files and in this instance one suggested Rule Set.

    8. The other worksheets in the File Inspector Excel file give the details of the grouped files. For example, the following screenshot shows our Java files.

      In your application, you would have many more files and language groupings, and therefore more worksheets. In addition, any files that do not fall into a File Inspector Group will display in the Other worksheet. Take a look at this more complex File Inspector output:

      This report shows that you would need to create several Rule Sets, as indicated in the Suggested Rule Set(s) column. In addition, after looking at the Other worksheet, you may want to add file extensions to a File Inspector group as well as to the associated Rule Sets. In summary, the File Inspector tool helps in determining:

      • additional Rule Sets to create (select Project=>Create Rule Set to create a rule set from the Globalyzer Workbench; click on the View Rule Sets button to quickly navigate to the Globalyzer Server when you are ready to customize the new rule set)

      • file extensions to add to existing Rule Sets
      • additional file extensions and language groupings to add to the File Inspector
      • out of scope directories and files to apply to your scan configuration

    Configuring Scans

    1. You should now have an Eclipse project, example-source-java, in the Workbench Project Explorer view. Before any other operation, make sure the project has a Globalyzer nature. Clicking the right mouse button on the top level project directory.

      If there is no Globalyzer nature, associate it using the following menu item (a project with a Globalyzer Nature has the menu right after this one):

      If there is no currently associated Globalyzer Nature, a Configuring Scans dialog will pop up. Click New, then Cancel. You will be configuring scans later on in this tutorial. The project should now have a Globalyzer nature.

      You will then notice that Globalyzer menu items have been associated with your Java project. For instance, by clicking the right mouse button on the top level project directory again, the following menu items appear:

    2. To configure how to scan code with Globalyzer, right click on the top level project directory and select the Globalyzer=>Manage Scans ... menu item. The dialog for managing scan pops up. Click on the New button to set up your first scan configuration. The Create/Edit Globalyzer Scan dialog appears.

      Fill in the name of Scan ("Tutorial Java Scan"), select the Rule Set for this code ("my_ruleset" for instance), give a short description ("A scan based on the tutorial Java rule set"). Select the src directory so the scan will run against the Java files. You can navigate the directory structure and select only some of the source files for your projects.

    3. When you are done with selecting your files and directories, click Next.

    4. You are presented with the Globalyzer Scanning page of the wizard. To disable or enable scanning for specific types, you check or uncheck the types in the Detect pane. These types correspond to the Detection Rules in your Rule Set, and tell Globalyzer what to look for. If selected, the scanner will detect and locate in your source code each of these categories of items: Embedded Strings, Locale-Sensitive Methods, General Patterns, and Static File References.

      This is also where you set Source File Encoding, which tells Globalyzer the file format of your source files. If your files match the default file format of your local machine, then leave the setting as SystemDefault. Otherwise, you can choose the correct file format from the dropdown.

      Note: The Source File Encoding field is an important field when it comes to setting up a Globalyzer Scan for your application. Globalyzer uses this field to determine how to open source files for scanning and for fixing i18n issues, such as externalization of strings. Usually, files are encoded in the default format of the local machine. However, sometimes source files may be in a different encoding. To ensure that files are read and written properly, Globalyzer will try to detect the encoding of a source file, regardless the Source File Encoding setting. As long as the source file has BOM bytes (bytes at the beginning of files that indicate the encoding), Globalyzer will be successful. This way, if most of your source is encoding in SystemDefault but there are some files encoded in a file format with BOM (e.g. UTF-16 with BOM), Globalyzer will be able to correctly handle differently-encoded files.

      The last set of fields, Comments, are used to instruct the Globalyzer scanner to skip over a line or block of source code, ignoring any i18n issues, and also to mark a line as To Do for later refactoring. Note that these comments will be inserted into the source code. You'll see later in this tutorial how you can also use "soft" statuses when you want to skip or ignore i18n issues without actually modifying the source code.

      Leave all the default values as they are for now. Click Next through the pages and then Finish.

      Close the Manage Globalyzer Scans dialog.

    You are now ready to scan your code.