Who is this Guide for?

This guide is for Java programmers interested in adding a new type of file that can be converted to NetCDF with the file converter. If you have little or no Java experience then this task will most likely be very confusing and difficult. In the interest of brevity there will be no explanations of the Java language, just how this program is implemented. If you do not know Java then this is probably not for you.

Also, a good working knowledge of NetCDF will be very helpful. This is easier to compensate for and learn if you have to. To find out more about NetCDF you can visit Unidata’s NetCDF page.

How Does the Converter Work?

When the user wants to convert a file, first a configuration file is created, each file type has specific data that it needs for the program to know how to convert it. Then, when the file is converted, a class reads in the data in that file first, and then a conversion function in the file is called. So the two most basic steps of converting a file are 1) Read in the metadata and then 2) Convert the file using that data.

The process is abstracted as much as possible to make adding new file types easy, this is done in several ways. First is that there is a base, “file type” class. CConfigFile is the base for all file types (all the file types extend CConfigFile), it will read in the data common to all files (like file names and attributes) as well as write the header for the NetCDF and write the out the data collected appropriately.

The data collection mechanism has also been generalized. A class called CDataFile is the mechanism for storing the data that has been read in. It uses the functions “AddData (double)” and “double GetData ()” to reach the data with. It stores the data like a queue, so the data must be read into it in the correct order. So basically, the class for the file type will read in the data from file, and put it into a CDataFile class. Then a method in CConfigFile will write out those CDataFiles into the NetCDF file for you.

The array CDataFile DimFiles [] appears frequently throughout the program. This will always be an array of CDataFiles for all of the variables: lat, lon, depth, time and the data itself. It will also be in that order, but if either depth or time (or both) don’t exist, then the data will not be the 5th value, the ones that don’t exist aren’t part of the DimFiles array (even though it will always have a length of 5). CConfigFile has a method that will return the index for the data in DimFiles, int GetDataIndex (CDataFile DimFiles []). This can come in useful.

How to Add a File Type

The best first step is to copy and paste the code from CTemplate.java. This is, as the name suggests, a template for adding a new file type, and it will have much of the necessary code already there, as well as a more thorough explanation of what you need to create a new file type.

You class will be initiated by the program (you don’t have to worry about how), it then has to read the metadata it needs from a file that will be already open and stored in the super class CConfigFile (named InFile). You can assume the file is in perfect condition, that all your data is there, if it’s not, some sort of exception will be thrown (or if there is a system error reading the file). Thought it’s not required, the current method for dealing with an error is to call the function CFileConverter.HandleError (Exception E, String ErrorFrom), where you send it the exception as well as where the function is (an example would be “CColumnConfig.BuildClass()”). This will pop-up a message to the user as well as stop the program.

Once the data has been read in, the class will be called once again, this time to convert the data. The class will be sent CDataFile DimFiles [] to store the data in as well as the input file and output file (this is not a basic Java output file, it’s a NetCDF specific class, but in a typical circumstance you’ll simply have to call functions with it, not write to it yourself). To find out more about the Java interface for NetCDF, you can visit Unidata’s Java site.

The specific implementation, file names, and similar things will be contained in CTemplate.java. You do have to do two other things to “register” your class type. If you aren’t implementing a GUI for your class type (GUIs are highly recommended, but you can choose not to implement one) then only one change is required. Go to CConfigFile.java, at the top there are instructions for making the one (simple) change. If you do implement a GUI then you need to include more things in you class file (these are also included with CTemplate.java) and you need to make four changes to CUserInterface.java, these changes will also be explained and clearly labeled at the top of the file. All the changes are very simple, most of which require adding on a new case to a switch statement, and should be obvious from the code there what to add.

Once you have made these changes and re-compiled the converter will now include your file type!

<< User's Guide