2010-12-19

Naming in Postgres

In both the SQL spec and various databases, many words are reserved and should not be used in identifiers (your names you assign to columns, tables, etc.). The Postgres 9 docs show a list of reserved words, a long list indeed.

In my own work, I don't want to be checking my possible new identifier names against that list all the time. Instead, I end all my SQL identifiers with an underscore. Examples:

  • customer_
  • first_name_
  • last_name_
  • city_
  • state_
  • zip_

This convention maintains readability without adding much to length. I've heard of people appending "_tbl " and "_fld" and so on to their identifiers to accomplish the same goal of avoiding conflicts with reserved words. But that is much harder to read, and gets old fast. The trailing underscore solves the problem, and is guaranteed to work. Section 4.1.1 of the Postgres 9 docs mention that the SQL spec will never define a keyword that starts or ends with an underscore.

Identifiers in Postgres 9 can be up to 63 characters long.

Identifiers can contain textual characters, even beyond the usual ASCII English letters, including accented characters. But personally I'd stick to ASCII letters to prevent discovery of bugs. An identifier can contain a digit, but must start with an alphabetic letter or underscore. The only allowed punctuation is underscore: No spaces, periods, quotes, etc. A dollar sign ($) is allowed by Postgres but not the SQL spec, so avoid it.

Identifiers in Postgres are case-insensitive. But for compatibility with other databases, use only lower-case letters.

You can create identifiers that contain spaces, ampersands, and other oddball characters by enclosing the identifier in quotes. But do not do this. Using quoted identifiers will cause nothing but pain over the long haul. For instance, give up the idea of having the column name be presentable as-is to a user. An app should always be responsible for taking the column name and then looking up a presentable name for display to users.

2010-12-15

Deploying Web Apps in Apache Tomcat via the "jFastCGI" Java Servlet

    When deploying web apps built in Web Edition of REAL Studio, you can either build a basic web server into your app, or you can place you app "behind" a separate web server using the FastCGI protocol as a conduit between them. FastCGI is just a protocol, some rules of the road, with many implementations in various web servers.

[A] Apache Tomcat
These brief steps here for Tomcat installation are described more fully in my blog post:

(1) Download version 7.  
That first "Core" zip will do.

(2) Unzip.

(3) On Mac OS X (and maybe Linux) fix file permissions.
I'm not sure about v7, but on previous Tomcats I always ran into permissions problems.
On a Mac I drag and drop the unzipped folder to free "BatChmod" app.
I turn on all "Options" checkboxes except "Clear xattrs". Click Apply button.

(4) Move the unzipped folder to the top of your home folder. 
I'm paranoid about problems with very long pathnames due to too many nested folders.

(5) Launch Tomcat.
(5a) In the Apache Tomcat folder, find the "bin" folder. 
(5b) Launch the Terminal program. (Command Prompt window in Windows)
(5c) Drag the "startup.sh" file to the Terminal, and press Return. (Use the .bat for Windows)
See several lines confirm startup.

Launch a browser, point it to:
You should see a Tomcat-generated page.

[B] Port-forwarding

For Windows, skip to step 4.

For Mac & Linux, forward port 80 calls to Tomcat's default of 8080.
For more info, read my blog post: 

(1) Open another Terminal window.

(2) Paste this:
sudo ipfw add 100 fwd 127.0.0.1,8080 tcp from any to any 80 in
and press Return.

(3) Enter your password in Terminal as prompted.

(4) Test by pointing a web browser to:
You should see the Tomcat-generated page.

Tip: Always hit your browser's Refresh/Reload button/command to force a fresh loading of the web page. Some web browsers, especially Safari, display a cached copy of web pages rather than asking for a fresh one. That caching behavior can really confuse your testing!

(5) Shutdown Tomcat.
(5a) Drag the "shutdown.sh" file to the same Terminal window where you started Tomcat.
(5b) Press Return.

[C] jFastCGI Servlet

(1) Download 2.0 of jFastCGI.

(2) Unzip.
You'll get a folder with 2 .jar files and a .pdf manual.

(3) In the Tomcat folder, navigate to "webapps" folder. 
(3a) Delete or move everything inside "webapps".
(3b) Create a folder named "ROOT" inside the "webapps" folder.
(3c) Create a new Welcome page, for testing. For example, save the following HTML5 source code to a file named "index.html" stored in that "ROOT" folder:

<!doctype html>
<html>
 <head>
   <meta charset="UTF-8">
   <title>Welcome</title>
 </head>
 <body>
   <p>Per Basil's example.</p>
 </body>
</html>


(4) Install servlet.
(4a) Create a "WEB-INF" folder inside the "ROOT" folder.
(4b) Create a folder named "classes" inside the "WEB-INF" folder, next to that index.html file you just created.
(4c) Move in both .jar files from jFastCGI download: 
• commons-logging-1.1.1.jar
• jFastCGI-2.0.jar
FYI: .jar files are simply zip files plus an optional manifest file, used for storing Java executable and related files.

When done, your files should look like this screenshot.

Ignore the "Joda Time" and the commons-logging.

(5) Deploy Servlet Create an XML file to be used as a "Deployment Descriptor" instructing Tomcat when and how to invoke the jFastCGI servlet.
(5a) Create a new text file. Use UTF-8 character encoding.
(5b) Name the file "web.xml" and store it inside the "WEB-INF" folder used above.
(5c) Paste the following:


<?xml version="1.0" encoding="UTF-8"?> <web-app 
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
                        http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
       version="3.0"
       metadata-complete="true">

<servlet>
    <servlet-name>FastCGI</servlet-name>
    <servlet-class>net.jr.fastcgi.FastCGIServlet</servlet-class>
    <init-param>
        <param-name>server-address</param-name>
        <param-value>localhost:9000</param-value>
    </init-param> 
</servlet>

<servlet-mapping>
    <servlet-name>FastCGI</servlet-name>
    <url-pattern>/*</url-pattern>
</servlet-mapping>

</web-app>

[D] Run.

(1) Launch Tomcat. 
Tip: In Apple's Terminal, you can press the Up arrow key to repeat previous command line. Press again for previous before that. Press Return to execute.

(2) Build a simple web app in REAL Studio.
(2a) Build as "Static FastCGI" using port 9000. This assumes you have no other apps listening on port 9000.
(2b) My app: Create a TextField named "nowField" with an adjacent button whose Action event handler is:
 dim now as new Date
 nowField.Text = now.SQLDateTime

(3) Launch web app
(3a) In a new Terminal window, type out the entire path to your built app, and press Return. For example:
/Users/basilbourque/Desktop/real_now/real_now.fcgi
Tip: I moved my built app "real_now" to my Desktop folder for convenience. 
(3b) You can verify the web app is running by finding its name in the "Activity Monitor" program on your Mac, or equivalent in other platforms. You may need to select "All Processes" from the popup menu that filters the list.

Later, to stop this process, press Control+C in the same Terminal window. There must be a more graceful way to shutdown a web app, but I'll look into that later.

(4) Test Tomcat by pointing your web browser to:
Hopefully you will see your web app!

Next challenge is to wrap my head around the URL mapping. Currently I am using "/*" in the tag above. The asterisk is a wild card. So that pattern means any and every url goes to my REAL Studio web app. That is not practical. Only some URLs should go to the web app, while others will go to static web files, Java Servlets, etc. I tried using other URL patterns, but could not get it to work correctly.

Lastly, for most real-world deployment, we would want to add SSL/TLS encryption to the web browser interaction. Tomcat certainly supports that. But that chore will wait for another day.

Web Edition of REAL Studio launched

REAL Studio 2010 Release 5 arrived this week, and now includes "Web Edition".

This tool is a huge breakthrough, allowing you to create desktop-style apps deployed in a web browser. You build web apps in the same manner as desktop apps -- drag and drop widgets to forms, add programming to the widgets, and write classes as well. All in the same language: REALbasic. Same code editor and debugger, same commands and libraries. Except of course the web app widgets are a little different and more limited given the limitations of browser technologies and given that Web Edition is a new 1.0 feature set though built on top of an established toolset.

The wonderful thing about Web Edition is what is not in it:

Well, actually, Web Edition has all those, but you the programmer don't see them. As a programmer you need know nothing about web technologies. Keep your brain in desktop-app mode, but deploy to a browser. Amazing.

2010-12-02

Logging Facility Built Into REAL Studio

REAL Studio 2010 has its own logging facility. Call the "System.Log" command, passing 2 arguments:

  • Integer, the level of logging.
  • String, the message to be logged.
You can find 9 constants for that number in System.LogLevelXXX:
  • LogLevelEmergency = 1000
  • LogLevelAlert = 1001
  • LogLevelCritical = 1002
  • LogLevelError = 1003
  • LogLevelWarning = 1004
  • LogLevelNotice = 1005
  • LogLevelInformation = 1006
  • LogLevelDebug = 1007
  • LogLevelSuccess = 1008
Note that this is different than the 6 log levels used by the Apache Commons Logging project. You might think that after a few decades the computing industry would standardize on this stuff, but no.

Example usage:
  System.Log( System.LogLevelInformation, "Your Message Goes Here" )

Messages you pass appear in the host OS' logging tools. On Mac OS X Snow Leopard 10.6:
  1. Run the "Console" app.
  2. Click the "Show Log List" toolbar button.
  3. Select the first item beneath "Files": "system.log".
    Your messages should appear there.
One BIG catch with this facility: Not all the log level constants work on Mac OS X. As documented, and as tested by me in REAL Studio 2010 Release 5, the 3 most benign log levels fail on a Mac:
  • LogLevelInformation = 1006
  • LogLevelDebug = 1007
  • LogLevelSuccess = 1008
So, only use the following on a Mac.
  • LogLevelEmergency = 1000
  • LogLevelAlert = 1001
  • LogLevelCritical = 1002
  • LogLevelError = 1003
  • LogLevelWarning = 1004
  • LogLevelNotice = 1005
This is an annoying issue. I recommend writing your own wrapper based on the Apache Commons Logging project by using an Interface to make logging calls throughout your app. Use the "LogLevelNotice" to report all the benign levels.