- NAME
-
Data Structures and Files
This page describes the various data structures generated as part
of Smart Code, and details how they are used in the generated code,
as well as their public programming API.
- INTRODUCTION
-
Smart Code can be customized from within X-Designer. Groups can be changed,
group elements can be added and deleted. Customizer properties for
network connection, and handler routines can be modified.
Most of these changes are handled through the smart code data
structure.
In C, this is passed into the callout routine as an argument.
In C++ and Java
it is the base class of the callout class whose doit() method is invoked
from a toolkit callback.
Since the Smart Code data object manages the customizations made from within
X-Designer, only the X-Designer code file, the stubs file
the group code files in the groups_<c|cpp|java>, and the
smart code header file are overwritten each time code is generated.
All other smart code files are only regenerated if they have been removed, and
do not have to be rebuilt each time a customization has been modified.
The Smart Code data structure is designed to work across the possible permutations
of language and toolkits available. The data structure has a C, C++ and Java
format, and works with X/Motif callbacks, Windows/MFC message handlers and
Java/AWT event handlers.
With Get/Set Smart Code, you should program the callout as you would a
raw callback or event handler, except that the user interface controls are
accessd and modified through toolkit independent group getters and setters rather
than through the toolkit API.
For Internet and Thin-Client smart code, the
callout is ready written and provides the networking functionality.
This callout has hooks for calling user-defined precondition/postcondition
routines, and for overriding the routines which send data to, and receive
data from the server.
- SYNOPSIS
-
Most of the fields in the C data structure, or the members of the C++ and Java
classes are private and are not documented here. These are used in the
X-Designer code file to configure your smart code - for example, there are
function pointers for the send, receive and out-of-band handler routines set up
in the Customiser; there is also a transport member - itself an object with chat()
methods to allow the callout to connect across the internet.
Public fields/members are the parts of the data object that
are intended for programming within user callouts and handlers. These
are:
The data structures below include only PUBLIC elements.
In the definitions below, GROUPNAME is the name assigned to a particular group,
GROUPCLASS is the name of the group class in the generated code, and CALLOUTCLASS
is the name of the class that corresponds to a particular callout.
Get/Set Smart Code
For Get/Set Smart Code the data fields/methods are intend to be used directly by the
programmer in user-defined callouts (or doit methods in classes) in the callouts_<c|cpp|java>
directory.
Thin-Client and Internet Smart Code
For Thin-Client and Internet Smart Code, the data structure/class is used by a
ready written doit() routine/method that checks user preconditions/postconditions,
connects to a remote server and uses default Send, Receive and Out of Band routines
for managing the data transfer to and from the server, unless the programmer has
overriden these routines. The default Send and Receive routines for Thin Client
serialize, send, deserialize and update the interface and would only be overriden in
special circumstances. For Internet Smart Code, the programmer will always provide a
Receive routine to manage the data returned from the web. If a Send routine is
provided, data sent is POST'ed to the web server. By default, Internet Smart Code uses
the GET method.
- DESCRIPTION
-
The Get/Set data structure/class is considerably simpler than the client-server
structures. However, their public interface is extended only with the PollInterval
getters and setters, which are used by the client to poll the server asychronously.
- Name
- is the name of the callback/method associated with
the data structure. For Get/Set this is useful if you are using a single callout to
service a number of user-interface callbacks and need to differentiate between
them. For Thin-Client and Internet, the Name is used on the server side to lookup
which server-side callout needs to be invoked for an incoming request.
- Group
- - the Group field/method is used to access
the group object associated with the callout. Since the group object makes
all toolkit-independant getters and setters available to the callout, the
code to provide a local handle on the group is generated as part of the callout stub.
- Client Data
- is currently only available for
C functions, and corresponds to the client-data field in Xt callbacks. It allows you to
pass arbitrary extra data into the callout. In C++ and Java you would provide getter
and setter routines for your user data within your callout class.
- Poll Interval
- is only used in Thin-Client Smart Code, and
controls the timing of asychronous polling of the server by the client. This is
akin to the REFRESH meta command in the head of an HTML document, allowing client-driven
push like facilities. It is intended that the server itself sets the poll interval
using the poll field or the setPoll() method - but the API allows the client to override
this request.
- Instances of Data Objects
- - by default, each
callout has its own instance of each and every data structure. Callouts can share
smart code data structures if the programmer modifies the GetNew...() routines
to return existing data rather than new instances.
- The warn method
- C++ diagnostics are handled through
the warn method. The default warn method on Unix writes to the standard diagnostic.
On Windows, calls to warn() display the information through an AfxMessageBox() call.
- Server-side Data Objects
- Server side data objects
allow access to the group and setting of the poll-interval through the poll field or
the setPoll/getPoll methods. The data architecture is the same as on the client side, where
in C, the data object is passed into the callout, while in C++ and Java the data object
is subclassed, and the user-defined doit() method is called.
- preconditions/postconditions and the ready written Internet callout
-
The generated callout for Thin-Client and Internet programming follows the sequence:
The asynchronous chat() also calls the receive() continuation routine each time
it connects to the server.
The receive routine follows the sequence:
- USAGE
-
The Smart Code data structures/methods are intended to be created by X-Designer in the
code that is generated to prime callbacks. For this reason, getter methods are defined
as public in the SYNOPSIS above, while setter methods are only documented for the
Poll Interval.
Send Handlers are called with the Smart Code Data Object, allowing access to the
group object etc, and a URLConnection object for updating the URL's content headers
and for writing data to the URL's OutputStream.
Receive Handlers and Out of Band Data Handlers are called with the Smart Code Data Object
and the Internet Data Object, which gives access to the URL's MIME Type, and its
returning InputStream.
- EXAMPLES
-
Examples of setting up smart code data structures can be found in the X-Designer main
code file, where Smart Code callbacks are set up on individual controls. Example code
is also generated in comments within callouts and Send/Receive handlers. Live example
code can be produced by running the Smart Code replay scripts, which produce an interface, and
generate working callouts. Finally, use of the GoLive! @ notation in the Thin-Client and
Internet customizer will cause live code to be generated that will update/read from the
control.
- SEE ALSO
-
Group Objects, Internet Data,
URLConnection,
InputStream and OutputStream
Send Handlers,
Receive Handlers,
Out of Band Data Handlers