Subclassing Existing Applications
This article may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. To maintain the flow of the article, we've left these URLs in the text, but disabled the links.
.gif)
Subclassing Existing Applications
Richard David Hodder
Most developers have a store of reusable code they rely on during development. Most (if not all) of our apps use or subclass things from this store. In this article, Richard David Hodder presents an approach for reusing application functionality across applications.
You create subclasses to reuse existing functionality in a class and to extend/change its behavior. You can "subclass" an application to reuse existing functionality in the application and to extend/change its behavior. I use the term "subclassing" somewhat loosely here, but I think it conveys the right intent.
Let's say that I have an existing application "Oingo" and I wish to create a new application "Boingo" that's based on Oingo. There are several possible reasons to subclass the Oingo application:
- Add functionality: I want Boingo to have all of the functionality of Oingo plus some new features.
- Substitute/override functionality: I want Boingo to have all of the functionality of Oingo with substitutions for some existing functionality (for example, an Import form that looks totally different).
- Remove functionality: I want Boingo to have all of the functionality of Oingo with some existing functionality removed (for example, remove the Import option from the menu).
The first approach that might come to mind would be to create a new project file for Boingo, within the Oingo application directory. This approach mixes code bases and leaves you at high risk for breaking Oingo while trying to extend behavior in Boingo.
The most direct approach would be to create a new directory for Boingo, copy all of the files from the Oingo application into the new directory, make changes/add functionality, rebuild, test, and distribute, right? The problem with this approach is that the "connection" between Oingo and Boingo no longer exists: They no longer stem from the same code base. There are now two distinct code bases: When changes to Oingo are made, the changes must also be applied to Boingo to maintain the same functionality.
In a perfect world, several things would happen:
- The Boingo project would have its own directory.
- The project file for Boingo would be pointing to the same code base that's found in the Oingo project file. This would allow the changes to be made to Oingo and "ripple" to Boingo.
- The project directory for Boingo should have markedly less code—only the code that implements the additions, substitutions, and removals of Oingo functionality.
- Changes to the application layer ("a-layer") code in Oingo would be inherited by Boingo.
- Changes to the a-layer in Boingo wouldn't be inherited by Oingo: Again I refer you to the subclass metaphor. Changes in subclasses don't affect the superclass; there's no "upward" inheritance.
One of my favorite quotes is, "Wherever you go, there you are." In a perfect world, you'd know the exact locations where functionality would need to be added, substituted, and removed before the originating application (Oingo in this example) is designed. This would allow you to do things like place hooks into and data-drive the application in order to control what's in an application and how to extend it. Most times it's not possible, and you may not know beforehand that the application needs to be "subclassed." That's why I included the word "existing" in the title of this article: You've already created the application. Now you want to make use of your existing work.
The keys to subclassing an application
The approach I'll present later for subclassing an application relies on being able to "trick" VFP into using other functions and classes. I'll present the general concepts first, and then I'll demonstrate how I applied them in Codebook applications I've written.
The keys to subclassing an application are:
- Managing the program stack (SET PROCEDURE)
- Managing the class stack (SET CLASSLIB)
- Managing the pathing (SET PATH)
- Copying the project file and massaging its contents
- Copying supporting files
****
Management of the program stack
When you call a function, VFP goes through the list of PRGs in the SET PROCEDURE list until it finds the function and then executes it. It goes through the list in the order of the PRGs in the SET PROCEDURE list. If two functions with the same name exist in one or more of the PRGs, then VFP executes the first one it encounters. Most of us have made the mistake of accidentally creating two functions with the same name. It gets really fun (read: frustrating <g>) when you keep modifying the function that's later in the stack, and then run the application and find that things still seem broken. It always happens at 3 a.m. when you're tired and out of caffeine. Consider the following three programs (Test, Foo, and Bar):
*-- TEST.PRG SET PROCEDURE TO FOO,BAR Hello()*-- FOO.PRG PROC Hello MESSAGEBOX("I'm broken") ENDPROC
*-- BAR.PRG PROC Hello MESSAGEBOX("I'm fixed") ENDPROC
When you run TEST.PRG, you'll always get the message box saying "I'm broken," no matter how many times you change the "I'm fixed" string in the Hello function in BAR.PRG. That's because when walking through the list of PRGs in SET PROCEDURE, VFP finds the Hello function in FOO.PRG first. The same goes for instantiating classes stored in PRGs: The first class encountered in the SET PROCEDURE list is instantiated.
You might be asking, "What's that got to do with subclassing an existing app?" Consider the following situation: Oingo has a stock price importing form that calls a function named ImportStockQuotes, which retrieves stock quotes from a Web site and imports them into a database. You want Boingo to import stock quotes from a file on disk rather than from a Web site. To change just the ImportStockQuotes "behavior" in Boingo, add a PRG to the Boingo project (for example, BoingoFunctionOverrides.PRG) and in that PRG create a function called ImportStockQuotes and fill it with the code to import the quotes from a file.
The only step left in order to override the ImportStockQuotes behavior is to make sure that Boingo loads BoingoFunctionOverrides.PRG into the SET PROCEDURE list earlier than Oingo's ImportStockQuotes. If you want to change the behavior of a class called DataImporter stored in a PRG, add a PRG to the Boingo project (for example, BoingoClassOverrides.PRG). In that PRG, create a class called DataImporter and fill it with the code that performs the behavior you want that class to execute in Boingo. You can be surgically "precise" with what you change by using this approach.
****
Management of the class stack
Managing the class stack is very similar to managing the program stack. When you instantiate a class that exists in a VCX class library, VFP goes through the list of class libraries in the SET CLASSLIB list until it finds the class and then instantiates it. It goes through the list in the order of the class libraries in the SET CLASSLIB list. If two classes with the same name exist in one or more of the class libraries, then VFP instantiates the first one it encounters. There's one important difference between managing the program and class stacks: The class stack can't contain two class library files with the same name. For example, suppose you had two directories (Oingo and Boingo) and each had a class library called DeadMansParty.VCX. If you executed the following command:
SET CLASSLIB TO ; \Oingo\DeadMansParty, ; \Boingo\DeadMansParty
you'd get the cryptic error "Alias name is already in use." Obviously, behind the scenes VFP is opening the class libraries as tables, and you can't have two tables with the same alias (DeadMansParty) open in the same workarea. You could get around this by using the ALIAS parameter of the SET CLASSLIB command:
As with the program stack, the trick to subclassing an application is to make sure that the a-layer class libraries for the subclassed app (Boingo) are loaded into SET CLASSLIB earlier than the class libraries from the superclass app (Oingo).
****
Management of the pathing
Managing the path by using SET PATH can also be important. Codebook developers can test their applications without having to build executables by taking advantage of path settings. Boingo may rely on the setting of path to open a file that's in the Oingo directory. ******
Copying the project file and massaging its contents
A few paragraphs ago I mentioned that it's important to make sure that Oingo and Boingo are based on the same code base. What's the quickest way to do that? Just copy the Oingo project file (PJX and PJT) into the Boingo directory, right? Close but no cigar. Now Boingo's project thinks that its directory contains Oingo's code: The pathing to the project items is wrong. The pathing needs to be adjusted so that the items in the Boingo project file point to the items in Oingo's directory. Some care has to be taken with this because some items still should exist in the Boingo directory—supporting files, for example. ******
Copying supporting files
Some items in a project support a framework or application and are application-specific, and therefore copies should be made of them, rather than pointing to the superclass app's files. Databases and tables are a good example of this. What good is it to point the Boingo project at Oingo's data, when one of the things that may be changing from Oingo to Boingo is data structures? Also, for development environment purposes it's better if Boingo has its own data structures, even if there are no changes. Other examples of supporting files are reports and INI files. Support files will differ based upon which framework(s) you develop with (for instance, Codebook, INTL, WebConnect, and so forth).
Frameworks can make most if not all of the keys to subclassing an application simpler to achieve because usually they've been addressed in the framework. For example, as you'll soon see, Codebook keeps a table of the programs and class libraries to load. By changing the framework slightly, these programs and classes can be loaded in a manner that supports the task of a-layer ordering of items in SET CLASSLIB and SET PROCEDURE.
Subclassing a Codebook application
Rather than trying to address all possible frameworks and libraries, I'm going to stick to territory that's familiar for me: the Codebook framework. ******
Management of the program and class stacks in Codebook
Codebook applications build a list of the programs and class libraries used by the application by querying the contents of the project file. In a function named BuildMetaData in Setup.PRG, the project file is opened with the alias "_project" and then the following query is run:
SELECT NAME, TYPE ; FROM _project ; WHERE !DELETED() AND ; (TYPE = "V" OR ; TYPE = "P") ; ORDER BY TYPE ; INTO CURSOR cTemp
Records with a type equal to "V" are class libraries (VCXs), and records with a type equal to "P" are programs (PRGs). The contents of this cursor are saved to a table called METADATA, which is built into Codebook executables. In another program named SetPath, the information in this cursor is looped through. All of the program records (type="P") are used to build a comma-delimited list of the programs in the project. The function then SETs PROCEDURE to this list of files. All of the class library records (type="V") are used to build a comma-delimited list of the class libraries in the project. The code then SETs CLASSLIB to this list of files.
Although this list is organized by type, this doesn't order the files so that the subclassed application's a-layer will get loaded earlier. Then I came up with an idea. I had the project file opened as a table, and I was looking at the Name field of the PJX file. The Name field uses relative pathing to point to project items. Therefore, framework files all started with ".." (for example, "..\common50\libs\capp.vcx"). Files that were in the a-layer, on the other hand, did not start with ".." because they were either in the project's directory or a subdirectory of the project's directory (for example, "progs\solvetheworldsproblems.prg").
I decided to change the contents of MetaData.DBF and reorder the records so that names not beginning with ".." float to the top of the list. Here's the modified query that I used:
I created a new field (LAYER) that holds the first two characters of the name of the file. This field is only used for the ORDER BY of this query. The framework doesn't use the field for anything. All non-a-layer code will have a LAYER equal to ".." and all a-layer code will not. Due to the fact that the period character "." has a lower ASCII value than the alphabetic characters, it was necessary to order the list by descending LAYER so that all a-layer records would be at the top of the cursor. Being at the top of the cursor, they get loaded into the respective stacks first!
****
Management of the pathing in Codebook
The main reason for managing pathing in Codebook is to create a development environment that allows you to develop an application without constantly having to rebuild the executable. When subclassing an application, Codebook must know two things: first, whether the current application is a subclassed application (like Boingo), and second, if it is, where the superclass application (Oingo) resides so that it can adjust its paths to point at Oingo. To solve this, I create a #DEFINE called APPLICATION_SUPERCLASS_DIRECTORY that contains the superclass's directory. This #DEFINE only exists if the current application is a subclass. Therefore I was able to use the #IFDEF directive to change the pathing in the SetPath function in Setup.PRG:
#IFDEF APPLICATION_SUPERCLASS_DIRECTORY LOCAL lcAppSubClassDir lcAppSubClassDir = ".."+ ; APPLICATION_SUPERCLASS_DIRECTORY + ; IIF(RIGHTC(APPLICATION_SUPERCLASS_DIRECTORY,1)!= ; "","","") lcPath = lcPath+ ","+; lcAppSubClassDir+"\PROGS, "+ ; lcAppSubClassDir+"\FORMS, "+ ; lcAppSubClassDir+"\LIBS, "+ ; lcAppSubClassDir+"\GRAPHICS" #ENDIF
#IFDEF will only execute its code if the #DEFINE exists (if the application is a subclass).
****
Copying supporting files and the project file and massaging its contents in Codebook
I created a simple tool called the Codebook Application Subclasser (see Figure 1).
.jpg){kind=link}
The form SUBCLASS.SCX is available in the accompanying Download file. I won't show all of the code here, but once the superclass application directory and subclass application directory are chosen, the following steps are taken:
Let's look at the last four function calls in this code snippet.
BuildIncludeFile—This routine creates the application include file for the subclass application (Boingo). It #INCLUDEs the application include file from the superclass application (Oingo). This is done so that #DEFINEs added to Oingo in the future will be "inherited" by Boingo. Boingo's include file can be added to manually: #DEFINEs added to this file don't affect Oingo (as I said before, inheritance doesn't move upward).
ModifyMainProgram—Main.PRG is the main program for Codebook applications. Main.PRG gets copied over from the superclass. ModifyMainProgram uses LLFF (low-level file functions) to add the equivalent of the following to the bottom of Main.PRG:
This has no effect on the code, but it makes sure that the next time the Boingo project is built, the aappBoingo class library will be added to the Boingo project.
ModifyStartCB—StartCB.PRG is a program that sets up the development environment (paths and so on) for an application. It isn't built into the application; it merely sets up the environment. ModifyStartCB adds code to StartCB so that the superclass application's paths are included.
CreateApplicationObjectSubclass—Every application created with the Codebook framework has an application object stored in AAPP.VCX. The application object holds global information for the application. When subclassing an application, it may be necessary to add or change properties and functionality on the subclassed application's application object. For example, Boingo might need to attach a timer object to the application object to remind the user to import stock prices (a feature not available in Oingo). Therefore, I create a subclass of the superclass app's application object and place it in the LIBS directory of the Boingo project's directory. Boingo-specific application object changes get made to this object. In order to avoid the class library naming collision problem mentioned earlier, I name the class library "AAPP<Subdirectory of CDBK50 To Create>" (for example, AAPPBoingo).
When to subclass an application
Just because cause you can subclass an application doesn't mean that you should. I can think of two occasions when subclassing an application would be appropriate:
If you sell a product and receive a lot of requests for "one-off" functionality.
If products will be internationally distributed. I worked on products that were developed in the U.S., but with the foresight to make them ready for the international market by incorporating Steven Black's INTL Toolkit (www.StevenBlack.com). As international versions of the product were developed, there was locale-specific functionality that needed to be incorporated. Spain required new reports, Italy needed enhancements to the import form, and so on.
Lessons learned
Having coding standards—particularly frameworks and standard directory structures and the like—made this process simpler: This is true for coding in general. I'm not suggesting that you use Codebook specifically (although four out of five VFP developers surveyed... <g>). Rather, I suggest that you pick (or create) standards and stick with them.
Also, use of the NEWOBJECT() function could actually get in your way because it hard-codes the location of the class library of the class you wish to instantiate. I've never really been a fan of this function for that very reason. I prefer to let the environment figure it out (particularly if I need to refactor classes into new class libraries), but that's just my own bias.
To find out more about FoxTalk and Pinnacle Publishing, visit their website at http://www.pinpub.com/html/main.isx?sub=57
Note: This is not a Microsoft Corporation website. Microsoft is not responsible for its content.
This article is reproduced from the December 2001 issue of FoxTalk. Copyright 2001, by Pinnacle Publishing, Inc., unless otherwise noted. All rights are reserved. FoxTalk is an independently produced publication of Pinnacle Publishing, Inc. No part of this article may be used or reproduced in any fashion (except in brief quotations used in critical articles and reviews) without prior consent of Pinnacle Publishing, Inc. To contact Pinnacle Publishing, Inc., please call 1-800-493-4867 x4209.