Soek is a Smalltalk application that provides a different way to navigate through documentation and source code of a Smalltalk library. Instead of the classic multi-list browser view in an image, Soek offers a flat view on all methods and classes and is build using the Seaside Web framework.

I discovered this way of publishing a framework when I worked with Rails and did most of my searches on Railsbrain.com. Not only I could easily find a particular class or method, it also showed me similar methods, other implementations, classes and their sources. The learning effect was great and it became my standard search tool and recommendation to others.

Wanting this for the Smalltalk community too, I started creating the application Soek in Cincom WebVelocity to have a similar view on libraries such as Seaside, Glorp, Cloudfork and even my own projects. I figured out how to parse the comment, declaration and body of a method, defined new syntax highlighting rules for Smalltalk and integrated the client-side search javascript functions from RailsBrian.com, kindly provided by Brian Chamberlain.

Because most libraries that I use are pretty stable, those documentation pages can very well be cached. So to make this happen, I developed a Publisher component that can generate all static pages to files creating a documentation set for each library. Next, I created a public Amazon S3 bucket to host all these documentation sets. Finally, I added a Launcher application as the front-end for this bucket to select which library documentation to explore. Available library information (name,version, s3-url,site-url) is accessed from a Amazon SimpleDB domain using Cloudfork ActiveItem.

The result is now available at soek.goodies.st

The Soek application is made open-source under MIT license and published in the Cincom WebVelocity Community.

Update: Current version fails to work in IE (6+). Use any of Firefox, Safari, Chrome instead for the time being.

If you want an existing package to register as a WebVelocity one and as a result make it visible to the browser page, you can evaluate this script:

(Store.Registry packageNamed: 'Your-Package-Name')
	propertyAt: #application put: true;
	propertyAt: #namespace put: 'Your-Namespace';
	propertyAt: #velocityThemeName put: 'Default'.

which I found when looking for the newApplication functionality in the image.

Logging can be very helpful in analyzing the (faulty) behavior of a server application in response to client requests. HypertextLogger is a simple component that produces HTML in response to logging instructions. Its main purpose it to provide a better readable log file. By choosing you favorite CSS, you can highlight what is important and leave other information unfocused (timestamps).

HTML log file

Upon creation of the logger, it produces a new .html file to which logging events are written. Because most Browsers can deal with open-ended (i.e. not properly closed by tags) HTML files, a single page can be used to collect lots of events. And if you let e.g. Apache serve these log files, you can monitor server applications remotely.

Features of the HypertextLogger are:

• the log can be custom CSS styled  (info,warn and error levels may have different emphasis)
• the log can have a custom pattern for each event (write your own formatBlock)
• you can use any HTML markup (e.q. links to other resources)
• by choosing a FileRollingPolicy you can control how many events are logged onto a single HTML file
• [update] can capture Transcript output and include it in the log

Using the logger

| logger |
logger := Philemon.HypertextLogger onFileNamed: 'myproject.log'.
logger debug: 'This is debugging info only shown if level == #debug'.
logger link: 'http://blog.doit.st' title: 'Smalltalk in the Cloud'.

Logger API

Some examples using the logging api. See class methods for tests.

logger blue: 'Text in Blue'.
logger escaped: '<escaped>'.
logger red:[ logger strong: 'Bummer' ].  "use blocks to combine the api"
logger logException: aSignal. "writes a stack"
logger enabled: true.
logger printTimestamp.
logger printCurrentProcess.

Customizing the logger

You can override the CSS styles and the format of each log entry.

logger css: aDictionary. "mapping between css-class and its definition"
logger formatBlock: [:logger :logLevel :content | logger print: content ]. "provide your own entry formatting"

Setup the FileRollingPolicy

Instead of producing one single big file, you can specify a policy to control log file creation.

logger daily. "every day create a new log (unless no events)"
logger maximumSize: 100000. "if size reaches limit then create a new log"
logger maximumEntries: 1000. "limit on the number of events"
logger refreshEvery: 10.  "10 seconds auto refresh by the browser"

HypertextLogger is implemented in VisualWorks Smalltalk and is available from the Cincom Public Store under MIT License.

Glare-DataServices is a framework for building Flex Remoting services in VisualWorks Smalltalk. In this post, I will guide you through the steps for creating a small application that demonstrates the use of the framework.

Install the bundle

First, you have to connect to the Cincom Public Store Repository. Then open the list of Published Items and load the bundle GlareDataServices. It includes the Glare bundle and Glare-DataServices packages. The required dependencies AT MetaNumerics and Opentalk are automatically loaded if not present.

Start the server

Class GlareServer has a singleton instance that will dispatch messages sent from a Flex application to Smalltalk services. To start the server, evaluate:

GlareServer current start

Now, you can visit http://localhost:8888 to see the current class registrations. You can change the portNumber on which the server is listening. For more settings and run actions, see the GlareServer class methods.

Create Smalltalk class: MethodFinderService

In this example, we are going to create a small AIR application called MethodFinder. Its GUI will have a search box and a list of method names that match the search criteria. The search itself will be performed by a Smalltalk service called MethodFinderService.

These are the steps for creating the service:

1. New Package: MethodFinder
2. New Class: MethodFinderService with superclass Glare.RemoteObject
3. Add instance method category operations
4. Define the method getSelectorsMatching

getSelectorsMatching

  ^(self function: #getSelectorsMatching)
    argument: #pattern type: String
    ; returns: SortedCollection
    ; body:[ :pattern |
		| sortedMatches |
		sortedMatches := SortedCollection new.
		"to keep things simple, we enumerate all symbols"
		Symbol allSymbolsDo:[ :e | (pattern match: e) ifTrue:[sortedMatches add: e]].
		sortedMatches]

Registration of this service to the GlareServer is required and done by evaluating:

MethodFinderService install

Create Flex application: MethodFinder

Now that the Smalltalk service is up and running, it is time to build the client application. Using the Adobe Flex/Flash Builder, create a new Flex AIR project called GlareMethodFinder. Open the GlareMethodFinder application component and paint a List (id=methods), a TextInput (id=pattern) and some Labels. On every change of the pattern, a new search will be requested.

Glare Method Finder

Your MXML file may look like this.

<?xml version="1.0" encoding="utf-8"?>
<mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" width="344" height="508">
	<mx:TextInput id="pattern" x="63" y="40" width="246" change="doSearch()"/>
	<mx:List id="methods" x="10" y="70" width="299" height="403"></mx:List>
	<mx:Label x="10" y="10" text="Glare Method Finder" fontSize="18"/>
</mx:WindowedApplication>

Configure Flex Remoting

The Flex compiler of the application needs to known about which AMF channels and destinations are going to be used. For this, two configuration files must be added. In the folder src of the project, add the file services-config.xml with:

<?xml version="1.0" encoding="UTF-8"?>
<services-config>
    <services>
        <service-include file-path="remoting-config.xml" />
    </services>
    <channels>
        <channel-definition id="my-amf" class="mx.messaging.channels.AMFChannel">
            <endpoint uri="http://localhost:8888/amf" class="flex.messaging.endpoints.AMFEndpoint"/>
        </channel-definition>
    </channels>
</services-config>

In the same folder (src) add the file remoting-config.xml with:

<?xml version="1.0" encoding="UTF-8"?>
<service id="remoting-service"
    class="flex.messaging.services.RemotingService"
    messageTypes="flex.messaging.messages.RemotingMessage">
    <default-channels>
        <channel ref="my-amf"/>
    </default-channels>
    <destination id="MethodFinderService" />
</service>

Now that we have the configuration files in place, we need to add a Flex compiler option. Open the Project properties and select “Flex Compiler” in the list. Change the options to the following line. (Windows developers need to change the path separator)

-locale en_US  -services ${DOCUMENTS}/GlareMethodFinder/src/services-config.xml

From Button click to Service call

Add the following script (using mx:Script) that implements the doSearch function. It creates a RemoteObject that will bind to the Smalltalk MethodFinderService. Using this remoteObject, you can send it the message getSelectorsMatching with the pattern argument.

private function doSearch():void {
	if (pattern.text.length == 0) return
	var service:RemoteObject = new RemoteObject("MethodFinderService")
	service.addEventListener(ResultEvent.RESULT, handleSearchResult)
	service.getSelectorsMatching(pattern.text + '*')
}
private function handleSearchResult(event:ResultEvent):void {
	methods.dataProvider = event.result as Array
}

Now the application is ready to find some methods. Run the application and start entering a pattern.

For this application to be really useful, we can add two buttons “Browse Implementors” and “Browse Senders”. We want these to open Smalltalk browsers in our running image. For this to work we can add two more operations to the MethodFinderService like browseImplementorsOf and browseSendersOf.

As can be expected, this exercise is left to reader.

Flex source code of this example can be found on glare.googlecode.com. The Smalltalk source code is available in the Cincom Public Store Repository in the package Glare-Examples-MethodFinder.

To make the VAStGoodies client work right from the VA image, I needed a service API in addition to the Seaside application that is running on VAStGoodies.com. Requirements for that service include “get all available configuration map names” and “get a download url for a particular version of a configuration map”.

Instead of implementing a full-blown end-to-end SOAP based Webservice, I decided to implement a much leaner RPC-style design that simply returns Smalltalk expressions.

If you visit the service with your browser then you will see something like the following plain text:

((Set new)
add: 'configurationMapNames';
add: 'configurationMapVersions';
add: 'index';
add: 'downloadUrl';
yourself)

An experienced Smalltalker directly recognizes this as being the storeString of a Set object. Most Smalltalk objects can represent themselves as an expression by sending the #storeString message.

Unmarshalling this content is simply done by a Smalltalk compiler. So in order to get all available configurationMap names, the client uses code like this:

expression := HttpClient new fetch: 'http://vastgoodies.com/services/configurationMapNames'.
avaliableConfigmapNames := EsCompiler evaluate: expression.

Sending the “index” request returns all available service selectors (as shown in the first example). Sending any other message will return an error page to protect the service from unwanted messages such as #halt

The Cloudfork project is available for the three larger Smalltalk implementations: Squeak/Pharo, VA Smalltalk and VisualWorks. For maintaining the ports based on the Squeak implementation, we use the Package-Exporters package.

For porting to VA Smalltalk, we are using the VAPackageExporter as explained by Adriaan van Os. One important feature is the ability to maintain the port based on the changes to a project rather than repeating the all-in-one export.

For maintaining the VisualWorks port of Cloudfork, I extended the Package-Exporters project with a VWPatchExporter that can be used to export changes in the VisualWorks XML format. Having this feature, I can write the following expression to export only the additions/removals and changes to our project:

VWPatchsetExporter
	fileOutPackageNamed: 'Cloudfork-AWS'
	relativeTo:  'Cloudfork-AWS-emm.76'
	withNamespace:  'Cloudfork'

There is still one issue related to namespaces. Because Squeak does not have namespaces support (yet?), extensions to classes that are not part of the project may be exported using the wrong namespace. Therefore, I always load the export first as a Change list to review the extensions and fix the namespaces by hand.

A possible solution to overcome this is to provide the VWPatchsetExporter with a mapping of qualified class names. Implementing the visualworksName as suggested by Package-Exporters, is not what I prefer.

Today I spent some time figuring out if and how I could change to default text font of the Smalltalk browsers in VisualWorks (76nc). For years I have been using my favorite coding font Dina (Win only) in any other tool such as Eclipse. Having this font also in VisualWorks would be very pleasing.

So I browsed through the source code of Look policies, Font policies and Font descriptions to find any clues. I was prepared to hack any method for this cause. Then I stumbled upon a little tool to assign Fonts to text styles:

NamedFontSelector new open

I picked my installed Dina font from the right list and assigned it to the style “fixed”. Then I opened the Settings tool and changed the Tools::textSize to Fixed. I gently hit Apply and saw my wish come true

Glare is a Flex Remoting and Messaging server written in VisualWorks Smalltalk by Philipp Bunge. I am extending his work with Glare-DataServices which basically provides a HttpServlet that dispatches operation invocations send from a AMF client (Flex,AIR) to Smalltalk objects.

To work with Glare-DataServices, you need Smalltalk classes that implement operations and ActionScript classes that have corresponding methods in which these operations are invoked remotely. Because both classes (client and server-side) must have the same signature, it is clear that code generation can be very helpful.

One of the requirements, also applied to the Pocogese framework (Flex on Rails), is that methods of each Service class must have metadata such as function name and argument types. Using the metadata of each operation, a code generation tool is able to generate ActionScript classes with the correct signature.

For Glare-DataServices, I am exploring a different approach that combines both the specification and implementation of each operation using a Block. Let me illustrate using a simple example:

SampleService>>computeSum
  " Answer a RemoteMethod that both specifies and implements the sum computation"

  ^( self function: 'computeSum' )
         comment: 'Returns the sum of two numbers'
       ; argument: 'left' type: Number
       ; argument: 'right' type: Number
       ; returns: Number
       ; body: [ :left :right |  left + right ]

You will notice that sending the message “computeSum” to an instance of this service will not perform the operation but instead returns a RemoteMethod with a body.

Having the operation metadata, a RemoteMethod can easily be translated to the ActionScript function implementation:

public function computeSum ( left : Number, right : Number , resultHandler : Function ) : void {
    var ro:RemoteObject = new RemoteObject ( "SampleService" )
    ro.computeSum.addEventHandler(ResultEvent.RESULT,resultHandler)
    ro.computeSum(left,right)
}

When Glare-DataServices receives a request from Flash (running ActionScript), it will lookup the RemoteMethod using the name of the function and evaluate the body of that method like this:

serviceOperation: functionName withArguments: aCollection
    " Find the registered RemoteMethod and evaluates its body using the arguments."

    ^ (self lookUp: functionName) body valueWithArguments: aCollection asArray

Method categorization is an important part of documenting the interface of classes, which is quite unique to Smalltalk to my knowledge. Therefore most developers spent time reorganization their methods in commonly known categories such as initialize-release, accessing and instance creation.

PhilemonToolMethodCategories is a goodie that contains some extensions to the standard browsers that deal with categorization. In particular, it offers a different “Move to category…” menu item that pops up a menu with existing categories and another submenu with suggested category names. You can change the default list on a per-user basis like this:

EmUser current storeObject: #( 'initialize-release' 'accessing' ) as: 'PreferredInstanceProtocolNames'

Browse Unsent Methods…
The Browser Class menu will have this new item that will search the image for methods defined in the selected class for which no senders could be found.You can use it to cleanup your class once it is more stable.

New Method Template
Furthermore, this goodie adds a nice little event hook that obsoletes the use of “New Method Template” ; just select the category to which you want to add a method and the template will be shown and selected for you to replace immediately.

This goodie is part of the “Philemon Tools” configuration map and can be downloaded from VAStGoodies.com

The Classes Interface Browser is a small search tool to quickly find a Smalltalk class or one of its methods. The two inputs fields on top provide filters for class names and method names of that class. From a selected class or method, you can open a Class Browser by double-clicking. Using the list popup menus, you can navigate (superclass, subclasses…) in the class hierarchy, add a breakpoint and navigate (redefined, overridden) in the method implementation hierarchy.

The “dots” button will popup a menu with the latest selections. De “inst” button will switch between instance and class methods. Another nice little detail is the method signature at the bottom of the window.

This goodie is part of the “Philemon Tools” configuration map and can be downloaded from VAStGoodies.com