This little Program Went to Market: Create, Deploy, Distribute, Sell, and Market Software and More on the Internet at Little or No Cost to You

Many of the tips, techniques, and tools discussed in this blog are demonstrated in a detailed step-by-step tutorial in the book, This Little Program Went to Market, by Annette Godtland.

The book takes a computer program through the entire process of creating, deploying and distributing a program, then selling and marketing it (or any other product) on the Internet. Read more.

Licensing Issues

Always check for licensing issues before you include a third party program with your program. Read the “License to Distribute” section of the license agreement for the version of the JRE that you plan to use, and make sure that you understand and follow the terms of that agreement.

Advantages of including the JRE

By including the JRE with my program, the user can install both my program and the JRE by downloading a single file, and then run just one install wizard. The user does not have to figure out how and were to get the required JRE. Nor does he have to stop in the middle of installing my program in order to go find Java.

I use Inno Setup to create my install wizard. My install wizard checks if the user has the minimum required version of the JRE installed. If he does, it installs just my program. If he does not have the minimum required version of the JRE, my install wizard asks if he wants to install it, and if so, installs the JRE that is included with my program. After installing my program, my install wizard deletes the JRE install file, freeing up space from a large file that is no longer needed.

Inno Setup, available free of charge, is a very comprehensive program for creating Windows install wizards.  Download Inno Setup from http://www.jrsoftware.org/isinfo.php.

Disadvantages of including the JRE

My Java programs are small. Even with all my program’s required resources, my setup.exe file is often less than 2 MB. The JRE installer adds 15 MB to the size of my setup.exe file, greatly increasing the file size. Larger files take longer to download. The disadvantage of including the JRE in my install wizard is that some potential users of my program may decide to not bother downloading my program if its download takes too long.

Offer Both

I decided to offer both solutions. The user may choose to download the version of my installer with the JRE, or the one without the JRE. I believe I would lose more potential users of my program if I didn’t include the JRE than if I did, so the default download option is the one with the installer. But then I also provide the alternative option to download the much smaller installer without Java if the user believes he has a valid version of Java already on his computer.

Conclusion

One basic rule to keep in mind when you create your program’s install wizard is always minimize the nubmer of steps required of the user. You don’t want a potential customer to give up just because too many steps or decisions were required to install your program.

By bundling the JRE with your program and letting your installer decide if it will be needed, you greatly simplify the installation of your program and its requirements.

What Minimum Version Should You Require?

In a moment I’ll discuss steps you can take to make sure someone doesn’t try to run your program if he doesn’t have the minimum version of Java installed on his computer. But first, what version of Java should you require as the minimum version?

Suppose you do your program development using the most recent version of Java, but you carefully avoid using any of its new features. Suppose your program could be run with an older version of the JRE, such as Java 1.3. Should your program state and enforce use of Java 1.3 as its minimum JRE version? Sun (now Oracle) recommends always using the most recent version of Java.

I went back and forth on this. I hated to force the user to install a newer version of Java if my program would work fine on the version of Java he already has on his computer. However, it is a poor business practice to claim a program will work in a particular environment if you haven’t actually verified that it will work in that environment. I wasn’t sure if I would very easily be able to test my program on the older version of the JRE.

Finally I decided that the surest way to warrant the quality of my program is to claim whatever version of Java I used to compile, build, and test my program as the minimum version of Java required.  So if I do all my development work with the latest version of Java, that is the version that I state as the minimum version of Java required for my program. Besides, Java technical support is only available for issues found in the latest version of Java.

Require the Minimum Version of Java When the Program Runs

In a prior blog post, Should You Create an .EXE Wrapper for a Java Program, I discussed my favorite free tool for creating an .exe wrapper, jStart32. An .exe wrapper is simply a small program file with an .exe extension that will call another type of program, in this case a Java program, with all the program’s required parameters.

Some of the settings for creating an .exe wrapper using jStart32 include:

• Minimal Java Version

• Display when no JRE found

• Display when JRE version is too low

By setting these options, the program’s exe wrapper won’t run on a computer that does not meet the minimum JRE requirements for the program.

Require the Minimum Version of Java When the Program is Installed

By placing the minimum JRE requirements on the .exe wrapper as stated above, you enforce the requirement only when the user tries to start your program by running the .exe file. But what if he instead tries to start your program by double clicking its executable .jar file? No minimum JRE requirement is checked when the user directly starts an executable .jar file.

To avoid such problems I would recommend that you also make sure the user has the minimum JRE installed on his computer when he installs your program. Your program’s install wizard should verify that Java is installed and that it is the same version that you require, or newer. You could then abort installation of your program if the computer doesn’t meet your minimum Java requirement. This would save the user from installing a program that he cannot use on his computer.

Conclusion

Set your minimum JRE requirement to the version of Java that you used to compile, build, and test your program. Enforce that minimum JRE requirement both when the program is installed and when the program is run.

But what should you do if he doesn’t have the minimum version of Java? The above steps would simply not allow such a user to use your program. It would be even more helpful if you instead helped him get the correct version of Java so he could run your program.  What to consider when setting that up will be the topic of my next blog article.

Check the License Agreement

Before you decide to use code that someone that else wrote, check the license agreement for that code. Are you allowed to use it for commercial use, or only for personal use? Are there any other restrictions?

Is the code bundled in a jar file? Are you required to keep that code in its original form? Are you allowed to redistribute the jar file?

If you are not allowed to redistribute an external jar file, do not use it in your program. You would not be able to sell your program, let alone run your program on any other computer, if you can’t redistribute the external jar file.

The rest of this article assumes the code you want to use is bundled in an external jar file which you are allowed to redistribute.

Build Your Jar File

If you’ve been working with Java, you will have learned that you can easily bundle all your code into a single executable jar file. But what do you do with the external jar files that your program requires?

I heard someone once suggest that you should unpack the external jar file, then bundle all its objects into your jar file. This would simplify distributing your program since you would then have everything in one jar file. However, this likely breaks the license agreement for your allowed use of the external jar file.

Instead, plan to distribute both your program’s jar file and the external jar file as separate jar files. For your program to still work, include the classpath to the required external jar file in the manifest of your program’s jar file.

Build an Install Wizard

How will your program’s jar file’s manifest know where the external jar file will be installed on the next computer? It’s easy if you control the installation of all the external jar files. You may do so by providing an install wizard for your program.

An install wizard can take any number of required resources for your program and install them where you want them on the user’s computer. Your install wizard should make sure that the external jar files are installed in expected locations relative to where your program’s jar file is installed. Then your programs jar file manifest should include classpaths to those expected relative locations of the required external jar files.

Conclusion

Read the license agreement of any external jar file that you want to use in your program. The safest way to package a redistributable external jar file with your program is to keep it in its original jar file form. Create an install wizard to install all your program’s required resources. By doing so, your program should be able to find and access all its required external jar files.

How Do File Type Associations Work?

File type associations associate types of data files with programs. The computer operating system recognizes a data file type by its extension, such as “.doc”, “.pdf”, or “.jpg”. Only one program may be associated as the default program for a particular file type at any time.  The install wizard of a program may automatically register a data file type with its own program.  A user may at any time manually change system settings so a data file type is assigned to a different default program. Therefore, the program associated with each data file type may be different on every computer.

In order for a program to work with the associated file type, the program must be coded to accept the name of a file as an input parameter. The program must then be able to read that data file, process the data in that file, and run successfully using the data that was in that input file. If the program requires data from more than one file, it must be able to locate the additional required files on its own, possibly based on the data that was in the first data file. The only input that will come into a program when a data file is double clicked is the name of the clicked file.

Manually Set a File Type Association

When you double click a file with an extension that is not yet associated with a program, Windows will prompt you to choose a program for opening that type of file.  This creates a file type association for files with that extension.

When you double click a file with an extension that is already associated with a different program, you will not get the opportunity to choose another program. If you want to manually change the program associated with a particular file extension, you must go through the Windows Control Panel options to assign a different program to that file type.

Automatically Set a File Type Association

Many programs set their file type association as part of their install process. This is preferred to expecting the user of the program to set up the file type association manually.

Another of my favorite free programs is Inno Setup.  I use it to create the install wizards for my programs. Inno Setup can be downloaded from http://www.jrsoftware.org. One of the many things you can configure for your install wizard using Inno Setup is automatic configuration of a customized file type association.

File Type Name and Icon

When you configure a file type association in Inno Setup, you can also indicate the file type name and file type icon. In other words, when your program is installed and the file type associations are automatically created, any file with that extension listed in Windows Explorer or on the computer desktop will be displayed using the icon and type name you assigned to that file type. This gives your program a much more polished look.

Scope of a File Type Association

File type associations may be set for either all users of the computer or only the current user. When you set the file type association manually as described above, it sets the file type association for the current user only. When you set a file type association automatically during the install of the program, you probably want it set for all users of the computer. However, current user associations take priority over all users of the computer. Current User associations will not be reset to match the new setting for all users.

This became a problem for me when I was working on one of my test programs.  I gave my data file for my Hello World program an extension of .hwd.  Before I set up my file type associations, I unwittingly manually assigned Notepad to open .hwd files.  Unfortunately, when I eventually set up a file type association for .hwd files to default to my Hello World program for all users of my computer, .hwd files still defaulted to open with Notepad for me.  The current user .hwd file type association to Notepad was an unwanted association that I needed to delete.

Windows XP had an option to delete any unwanted file type associations. There is no such option with Windows Vista and Windows 7.  To get around this problem, I recommend another of my favorite free programs that I found, Unassoc.exe. It may be used to remove any unwanted file type associations in Windows Vista and Windows 7. You can download Unassoc.exe from http://www.winhelponline.com/articles/231/1/An-Utility-to-Unassociate-File-Types-in-Windows-7-and-Vista.html

Can You Claim Any File Extension as Your Own?

Actually, you can. There is no global database where you need to register your use of a file extension for your program. There is nothing that will prevent you from associating your program with an already used file extension. However, it is to your advantage to try to come up with a file extension that no one else (or at least, not many others) are using. Otherwise, there may be data files out there for other programs that would not work with your program.

Conclusion

Creating file type associations is one more deployment step that makes your program easier for others to use.  Write your program so it accepts the name of a data file as input.  Then set up a file type association as part of the installation of your program.

Two Reasons to Obfuscate Your Code

One reason to obfuscate program code is to protect your intellectual property. You don’t want someone else to decompile your code and use pieces or all of it as he wishes. Though you can’t prevent someone from decompiling your code, if he can’t understand the code, your coding secrets may remain secret. He may decide to not use any of your code in his own programs if he cannot figure out what the various parts of your code do.

Another benefit of obfuscating program code is to improve performance. How can obfuscation improve performance? First, most obfuscators remove unused classes, variables, and methods, thus reducing the size of the executable files. Many of the longer names you used for objects, variables, and methods are changed to smaller, meaningless names, so the executable file will be smaller. Smaller executable files load faster and consume less memory. Some obfuscators may also move code around in ways that improve performance.

Reasons to Not Obfuscate Your Code

A big disadvantage of obfuscated code is that it is normally very difficult to debug. This isn’t as much of a problem with Java because Java obfuscation is performed on the byte code, not the source code. The source code will still be untouched for debugging. However, if you receive a runtime error with a stack trace, it could be more difficult to locate what triggered the error, because the stack trace will give the identifier names and line numbers based on the obfuscated byte code.

As you decide whether to obfuscate your code, be aware of the limitations. At best, obfuscation merely makes it time-consuming, not impossible, to reverse engineer a program. Obfuscation makes your code a little more difficult for others to examine for security weaknesses. However, when security is important, you must use measures more effective than obfuscation.

Let a Program Do It

What’s the easiest way to systematically rename identifiers, move code around, and make it difficult to read? Let a program do it. ProGuard is another of my favorite free programs. ProGuard is an open source program that obfuscates Java program code and performs code optimization. It does all its work on the generated class files, never touching the source code.

You can download ProGuard from http://proguard.sourceforge.net/. One of the many features I like about ProGuard is that it can be run as an Ant task, making code obfuscation an automated part of my build process.

Conclusion

If you obfuscate your code, it will be more difficult, but not impossible, for others to examine the coding techniques you used, and to copy your code. Obfuscating your code may also make your program perform better. However, obfuscating your code may make your program more difficult to debug. Whether or not you should obfuscate your code is something you must decide for yourself.

What Should You Include in a Readme.txt File?

Include any combination of the following in your readme.txt file:

• Name, version, description, and/or features of the program.
• System requirements.
• Install, uninstall, configuration, and operating instructions.
• Files list.
• Credit, acknowledgments, contact information, and copyright.
• Known bugs and a change log.

It is up to you which items you feel would be useful to users of your program, and the level of detail you should provide.

How to Create a Readme.txt File

Like the license agreement file, Create a Software License Agreement, the readme.txt file should be a simple text document.  Create the readme.txt file using a simple text editor, such as Windows Notepad. Every computer should be able to recognize and open a .txt file with a simple text editor.

When you create the readme.txt file, insert carriage returns at the end of each line of each paragraph. That will keep your  text nicely formatted whether or not the user has word wrap turned.

Also, by creating the readme.txt file as a simple text document, it may easily be used as input to other applications. For example, the program I use to create the install wizard for my programs can import the readme text from a simple text document and give the user the option to view the text when the program is installed.

Conclusion

The readme.txt file should identify your program, help the user start using it, and lead him to what to do next if he runs into problems.  Create a readme.txt file that is easy to read with the simplest of text editors.  Remember, the readme.txt file may be the first thing the user reads about you or your program.

What Should You Put in a License Agreement?

You may write your own license agreement, including whatever you feel is important. I suggest you read through the license agreements of other software you’ve purchased, especially those that might be similar to your software, and choose the topics and thoroughness that you liked most. Also be aware of things that you didn’t like about others’ license agreements. For example, blocks of text in all capital letters are difficult to read.

Legal considerations of what should be included, and the exact terms to use, is beyond the scope of this blog entry. Consult an attorney if you have specific questions about the content of your license agreement.

Make Your License Agreement Easy to Read

You’ll want users to be able to read your license agreement with the simplest of editors. Do not force the user to purchase a copy of Microsoft Office or to install Adobe Acrobat Reader so he can read your license agreement. Such requirements would only persuade the user to not bother reading your license agreement.

A common practice is to create the license agreement using a simple text editor, such as Windows Notepad, and give the license file an extension of .txt. Every computer should be able to recognize and open a .txt file with a simple text editor.

Another consideration is that even with the simplest of editors, the user may not have word wrap turned on when viewing your license agreement. You don’t want text disappearing off the right edge of the text viewer to prevent him from reading your entire license agreement. Insert carriage returns to end each line of each paragraph. Keep each line short. It is better to have the lines too short than too long.

Also, by creating your license agreement as a simple text document, it may easily be used as input to other applications. For example, the program I use for creating the install wizard for my programs can import the license agreement from a simple text document and display agreement during the install process.

Require Acceptance During Program Install

The only chance you will get to actually enforce the terms of your license agreement is by making the user’s agreement a condition of the installation of your program. You may easily set this up if you use another of my favorite free programs, Inno Setup, for creating your program’s install wizard. If you created your license agreement as a simple text document, Inno Setup can show the user the text from that document during installation of your program, and cancel the installation if the user does accept it.

Of course, that does not guarantee that the user really does agree to it, or even that he actually read your entire agreement. But at least you can be assured that he really did consent to the terms of your license agreement.

Make Your License Agreement Easy to Find

If you want a user to honor the terms of your license agreement, he has to be able to easily find your license agreement. Though you may have shown him the license agreement when he installed your program, he may have reason to check the terms of your license agreement again at a later date. For example, after using your program for awhile, maybe he is wondering if he is allowed to install it on a second computer, make backup copies, or sell it to someone else.  Whether or not you allow these things should be clearly stated in your license agreement.  Consider making your license agreement easy to find by adding it to the Windows Start Programs menu and/or by adding it to your website.

Conclusion

A license agreement is an important part of making your program market ready. You must make it clear what you will allow and won’t allow the user to do with your program. Then make your license agreement a condition of installing your program, make it easy to read, and make it easy to find. None of this guarantees every user will honor the terms of your license agreement, but at least you will have made the conditions of use known and he will have accepted your terms.

Why Not Just Use an Executable Jar File?

I first experienced the problem with double clicking executable jar files when I gave my daughter a copy of one of the first programs I was working on. I sent her the executable jar file and instructed her to double click the file to start my program. I had many Java tools installed on my computer.  When I installed those Java tools, file associations were set up so double clicking a .jar file would automatically call Java. However, my daughter had an unpack utility installed on her computer. The unpack utility was for unpacking any packed files, including jar files. So her computer had file associations set up so double clicking a .jar file would automatically unpack the jar file. Double clicking my program’s jar file on her computer unpacked it instead of calling Java.

Therefore, double clicking an executable jar file may have different behaviors on different computers. But as stated above, for your program to be market ready, users should be able to start your program by double clicking a file.

Could you Change the File Association?

You could code the installation of your program to automatically set a file association for .jar files to call Java. Then you would be assured that double clicking your executable jar file would start your program, at least until someone did something to change file associations on that computer again. However, I think changing such file associations for file types that may be used by many different programs takes too many liberties with another’s computer. Don’t you hate it when you install a program and it manipulates settings you didn’t want it to change?

Create an EXE Wrapper

Instead, I prefer to provide a separate file the user can double click to start the program. In other words, I create an .exe wrapper. An .exe wrapper is simply a small program file with an .exe extension that will call another type of program, in this case a Java program, with all the program’s required parameters. Double clicking that .exe file provides the exact response one has come to expect from .exe files. Plus, your program then has no dependencies on a file type association.

Doesn’t That Limit Your Program to Windows?

OK, so you’re thinking you went through all the trouble of writing a program in Java so it can run on any operating system, and now I am asking you to restrict it to Windows by starting it with an .exe wrapper.  Yes, it is true that the .exe wrapper I’m asking you to put around your program runs only in Windows. But take a look at other programs that are available for many different operating systems. Notice that they provide different installers for each operating system, even for those programs that were created using Java. Create the .exe wrapper only for the installer you create for the Windows operating system. You could provide other installers, and maybe other wrappers, for other operating systems.

jStart32

I looked at a few of the available free programs that I found that may be used to create an .exe wrapper for Java programs. Though it is an old program, and it has a quirk I need to work around, I found jStart32 to be by far the easiest to use. You can download jStart32 from http://sourceforge.net/projects/jstart32/.

What’s its quirk? It doesn’t recognize icon libraries. When you create the .exe wrapper, you may specify the .ico file for your program’s icon. jStart32 assigns the first icon in the icon library, which is typically very low resolution, as the program’s icon. See my blog article on Create Your Own Icons for an explanation of icon libraries and how to create your own. Fortunately, I can get around this quirk by assigning the full icon library to the .exe file as part of my program’s install wizard. This replaces the default, low resolution icon that was assigned by jStart32.

Conclusion

Make your program market ready by making it easy to use. Make it easy to use by allowing the user to start your program by double clicking a file. Therefore, one more step in deploying your Java programs should be to create an .exe wrapper for the Windows version of your program.

jStart32 makes it easy to create the .exe wrapper. However, if you use jStart32 to create the .exe wrapper, assign a full icon library to the .exe wrapper as part of the install process of your program.

The JavaHelp System may be used to create a very good, easy to use, user’s guide for your program that will run on any operating system. If the program you are creating the help system for is a Java program, you may also integrate your help documents into your program.

The JavaHelp System

The JavaHelp System is an open source help system framework that is highly customizable and easy to integrate into Java programs. The JavaHelp System comes with a toolbar, content pane, and navigation pane, and supports a table of contents with an unlimited number of content levels, a searchable index, and full-text search database.

You may download the JavaHelp System from http://javahelp.java.net/.

Creating Your Help Documents

To create the most basic JavaHelp System:

• Create a simple HTML file for each topic of your help documentation.
• Create an XML file that defines the tree structure and text to be used in your table of contents.
• Create an XML file that maps each topic of the table of contents to the appropriate help files.

Here is a screen shot of a basic JavaHelp System using the default view configuration. This help system was created for my sample Hello World application with help topics of Who, What, When, Why, and How. Each topic has a separate help page. When a topic is selected in the left pane, its corresponding help page is displayed in the right pane.

All the window layout, navigation controls, and toolbar options are provided by the JavaHelp System. All I needed to provide were the HTML help files and two XML files.

Integrating the JavaHelp System into Your Program

The JavaHelp System has a complete API interface, made to be accessed from your Java programs. Using standard Java ActionListeners, you can program any button, menu item, or other Java component of your program to launch the JavaHelp System. Each ActionListener can be programmed to open directly to its own topic. This allows you to provide context sensitive help to your program.

User’s Guide

When creating online help for my programs, I like to create an additional separate program which does nothing more than open the same JavaHelp System to its main page. Users then have access to all my help documentation without needing to first open the program for which it provides the help. This second program is my User’s Guide which my program’s installer adds to the user’s Windows Start Menu.

Integrating the Help Documents into Your Website

Because the help pages of the JavaHelp System are simply HTML files, it is easy to include any or all of the help pages that you created for your program, directly into your website. This allows your website visitor to learn more about your program before he decides to download or buy your program.

Advanced Features

The basic help system is probably sufficient for a fairly small program. However, if the program is large and needs a lot of help documentation, it might be worth adding an index, a glossary, a favorites list, and maybe even search capability. These capabilities too are all available through the JavaHelp System.

Conclusion

When I was trying to get my first program ready for market, I considered other alternatives for my online help documentation. However, I did not like the effort that would be required to program all my own pop-up windows for help within my program. I did not like the expense required to create a PDF help system with table of contents capability. And I thought creating a basic set of HTML help pages lacked many ease of use features that I thought were needed.

I was thrilled when I discovered the JavaHelp System. The JavaHelp System made it easy for me to provide a full functioning help system to my programs with a minimal of effort. And best of all, it is available for free!