<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Oak2 Basics</title>
</head>
<body>
<h1>Oak2 Basics</h1>
<p>Hi, if you are reading this document it is probably because you are
interested in Oak2 but you actually don't know exactly what is Oak
neighter how it works.</p>
<p>If this is the case, you are reading the correct document, this text
exists to provide an introduction in how to use Oak2, how it works in
a way you be able not only to use Oak2 to create your own
applications, but also to contribute with components, toolkits and
other things.</p>
<h2>Why Oak2?</h2>
<p>Well, it's named Oak2 because of its father project, Oak. Oak2 is a
architectural revision of Oak.</p>
<h2>Ok, so why Oak?</h2>
<p>Two reasons, the first is that it is a three letter name, so it is
easy to type. The second is that the oak tree has very very many
branches, this applies to Oak. Oak is a tree of classes to support
perl development.</p>
<h2>Duh, I was not asking about the name, but why does Oak exists?</h2>
<p>Ah... ok... Oak was created when I was on the team that was developing
an ESP (email service provider) software infra-structure. And we
realized that there wasn't any framework to help perl developers in an
enterprise development. There weren't tools to handle data persistence
(I mean more than DBI do), to handle authentication, authorization,
business control, and even interface.</p>
<p>When I started in web development with perl I did fill my cgi file
with a lot of prints, to print the page I wish to show. Many people
still do that way, and there's nothing wrong with it, but it just
doesn't fit in an enterprise environment, you need much more low-cost
maintainance, high customization and that's just impossible with
prints into the cgi file.</p>
<p>The first step forward was the use of Text::Template, in this way the
cgi didn't need to have lots of prints anymore, just one. But that
wasn't enough and we built an entire framework that made much easier
all the work and made the maintainance much cheaper than before.</p>
<p>But as we developed the framework while we were developing the
application itself, the framework wasn't so perfect as we wanted to
be. So this is why I started Oak in August 2001.</p>
<p>Short answer: In a time we have frameworks like J2EE, like .net, like
many others, it's necessary to give perl the power needed to be used
in an enterprise environment. Oak exists to make the work of the
application developer (not only script developer) easier.</p>
<h2>So, what was wrong with Oak that made necessary creating Oak2?</h2>
<p>There is one huge change and some minor changes. The huge change is a
new aprouch to object oriented programming, that is including event
handling, time sense and customization as fundamental parts of OOP,
and in this way, Oak2::Object already does such things. Minor changes
include changing prints in Oak::Web components for return. Better
definition of Oak::Filer. Resolving inconsistencies, changing the way
Components are seen inside Oak etc.</p>
<h3>Event Handling</h3>
<p>Events are an important part of Object Oriented Programming, specially
when you're dealing with complex systems. For those who know database
systems, this is very much like triggers, except that it can be
applied to any object in any place (including Entity classes in
Mysql).</p>
<p>Just to illustrate, I'll tell when this can be usefull. You can add a
event into a account payable in a way that when the account is paid it
closes the order you made. Actually, the event mechanism is the key
to create a integrated but not tied system.</p>
<h3>Time Sense</h3>
<p>The objects need to know that time is passing. I.e.: A due bill must
know it's due so it can calculate how much must be paid because of the
late.</p>
<p>This is also usefull for some reality representations. I'll be
explaining this better in other documents.</p>
<p>P.S.: This isn't implemented yet, as I really still don't know how to
make it nice.</p>
<h3>Customization</h3>
<p>To explain this I'll use an example based on Java Swing API.</p>
<p>Let's imagine you have a swing application. Now imagine you want to
make the components to check into JAAS if the user has permission to
see that component, and you want it applied to all components of your
application. I.e.: Some text fields to be read-only or read-write
depending on user's permissions.</p>
<p>How would you do it?
<ul>
<ol>Create a subclass for each component you use implementing
this feature</ol>
<ol>Create a subclass for java.awt.Component and reimplement
the entire swing</ol>
<ol>Learn to use Aspect Oriented Programming.</ol>
</ul>
<p>The Customization concept is very much alike AOP, but with an
important difference. You don't have to say "execute before" or
"execute later". You implement it as if you were implementing a
subclass, with the subtle difference that instead of calling SUPER,
you call ORIG. And you actually don't have to call ORIG, if you want
to completely replace that method, you just do it.</p>
<h2>Enough of introduction, show it...</h2>
<p>Everything starts from Oak2::Object, this class defines:</p>
<ul>
<li>How to instantiate an object</li>
<li>How the properties are handled</li>
<li>How events are handled</li>
<li>Error handling</li>
</ul>
<p>I'll talk about each of these topics in detail:</p>
<h3>How to instantiate an object</h3>
<p>Oak2::Object implements the method new that do all the required code
to create an object in perl. This method calls the method constructor
and after_construction that are responsible for initializing the
object.</p>
<p>In this way, nobody should implement the method new, but every object
will be instantiated by the method new.</p>
<p>Every class that wants to do something when initializing should
implement the method constructor, but everytime you overload this
method you must remember to call SUPER.</p>
<p>And now a great difference from Oak 1. The introduction of the
"restore" concept. At any time, it should be possible to store an
object in some media (similar to object serialization in Java), and at
any time it should be possible to restore that object in the state it
was before storing. This is done with the Factory classes. One example
of a factory class is the Oak2::XMLObjectFactory. But be carefull,
each factory stores/restores an specific set of caracteristics, and
you should pay attention when storing the object.</p>
<p>The important thing in the restore concept is the Object Unique
Identifier (objuid), this identifier is composed by the class factory
that generated its output followed by a ; and the parameters to the
factory. In the case you store an object using the XMLObjectFactory in
the file obj.xml, the objuid would be
'Oak2::XMLObjectFactory;filename=obj.xml'. So, you can compose the
objuid at any time if you know the information the factory needs. It
will help you a lot in the future, believe me.</p>
<h3>How the properties are handled</h3>
<p>Oak2::Object implements the methods get, get_hash and set. This are
the gateways to the object's properties. The method get can receive
one or more parameters and will return as a list the values.</p>
<p>The method get_hash is very similar to get (actually, the method get
is a wrapper to get_hash) but instead of returning a list of values it
returns a hash with the name of the property as the key and the value
as the value.</p>
<p>The method set is used to change the value of some property. It
receives a hash with the properties being changed.</p>
<h3>How events are handled</h3>
<p>The events in Oak2 are very alike with the Java event infrastructure,
but with some add-ons...</p>
<p>The concept is that you have an object (or class) that fires events
and you have listeners for these events. The big difference for the
java infrastructure is that a listener can be of one of these types:</p>
<dl>
<dt>self</dt><dd>execute METHOD on this object</dd>
<dt>static</dt><dd>CODESTRING to be executed in eval. the return is the MD5 sum of the code</dd>
<dt>restorable</dt><dd>OBJUID to be restored and then the METHOD to be called.</dd>
<dt>dynamic</dt><dd>object REF to be used to call the given METHOD</dd>
</dl>
<p>Now, one by one:</p>
<p>Self is a listener to be used by the same object or class that fires
the event invoking some specific method.</p>
<p>Static is a listener that is just some perl code in a string that will
be eval'ed when the event is fired.</p>
<p>Restorable is a listener of an object that should be restored before
calling some specific method.</p>
<p>And finally, dynamic is some object that wants some method to be
invoked when the event is fired.</p>
<p>Point to me, in Java you need to implement an specific interface to
register yourself as a listener, here you simply say "hey, call this
method in this object".</p>
<p>The other conceptin the event handling is the event code. When
registering a listener you should tell which event you're willing to
listen to. The documentation for each class tells you which events are
dispatched.</p>
<h3>Error handling</h3>
<p>There is few to say here, because we just use the Error
try/catch/otherwise/finally interface. Each class documents which
Errors it throws.</p>
<h2>Moving on, now to Oak2::Component</h2>
<p>Wow, we finally saw the basic principles of Oak2 let's start to see
more...</p>
<p>The Oak2::Component class introduces the concept of some object own
other object, I mean, some Component may have subcomponents, just
that. If you see the documentation of Oak2::Component you'll see that
it doesn't make much more than that. The important thing is that
*every* component *must* have a name property setted.</p>
<hr>
<address><a href="mailto:daniel@ruoso.com">Daniel Ruoso</a></address>
<!-- Created: Wed Apr 6 18:28:58 BRT 2005 -->
<!-- hhmts start -->
Last modified: Wed Apr 6 18:37:42 BRT 2005
<!-- hhmts end -->
</body>
</html>