2001-09-09 21:48:07 +04:00
|
|
|
____ _ ___ _____
|
|
|
|
THE | _ \| | |_ _| ___|
|
|
|
|
| |_) | | | || |_
|
|
|
|
| __/| |___ | || _|
|
|
|
|
|_| |_____|___|_| DOCUMENTATION
|
|
|
|
|
|
|
|
[Stylistic Note: The quote character is ". The apostrophe is '.
|
|
|
|
Functions and methods end with (). Caps are used to indicate a new
|
|
|
|
term. Variables are quoted, method names are not.]
|
2001-05-05 11:12:56 +04:00
|
|
|
|
|
|
|
_______________________
|
|
|
|
CHAPTER 1: INTRODUCTION
|
|
|
|
| Wherein the author whines about the people who asked for this
|
|
|
|
| document and denies all responsability for its upkeep.
|
|
|
|
|
|
|
|
People said they wanted documentation.
|
|
|
|
|
|
|
|
So.
|
|
|
|
|
|
|
|
Here it is.
|
|
|
|
|
|
|
|
Documentation.
|
|
|
|
|
|
|
|
Not that it's going to be very thorough or anything. Since I change
|
|
|
|
major parts of my codebase on an hourly basis, and I update the
|
|
|
|
documentation on an annual basis, this is not going to be of much use
|
|
|
|
to anyone who expects it to be accurate.
|
|
|
|
|
|
|
|
I warn you right now: if you complain about inaccuracies, I'll just
|
|
|
|
give up any pretense of writing documentation.
|
|
|
|
|
|
|
|
|
|
|
|
______________________
|
|
|
|
CHAPTER 2: THE CONCEPT
|
|
|
|
| Wherein services are explained to be the Saviour of the human race
|
|
|
|
| and an attempt is made to remove some of their mystery.
|
|
|
|
|
|
|
|
Services are a key concept to the PLIF architecture. They are the PLIF
|
|
|
|
version of XPCOM components, DOM interfaces, C++ pure virtual classes
|
|
|
|
or operating system APIs. They abstract out functionality using Perl's
|
|
|
|
polymorphism support so as to make consumers implementation-agnostic.
|
|
|
|
|
|
|
|
66-----------------------+
|
|
|
|
| But what does it all |
|
|
|
|
| _mean_, Austin? |
|
|
|
|
+-----------------------99
|
|
|
|
|
|
|
|
Imagine you want to order Pizza. The typical thing to do is call
|
|
|
|
Domino's Pizza, place your order, and await the food at your front
|
|
|
|
door. But what if you're on holiday, and Domino's aren't available in
|
|
|
|
that area? Your call fails, because you are unable to get Domino's to
|
|
|
|
ship pizza to you from your home town to your hotel on a different
|
|
|
|
continent, and thus you starve and die.
|
|
|
|
|
|
|
|
Clearly this is suboptimal.
|
|
|
|
|
|
|
|
Here is an alternative way of ordering pizza. Instead of picking up
|
|
|
|
the telephone, you pick up the business directory (aka, the yellow
|
|
|
|
pages). You look up "pizza takeaway" and search for the first entry
|
|
|
|
that claims to support deliveries. (I say "claims to support" because
|
|
|
|
marketing departments are often out of touch with reality.) Next, you
|
|
|
|
pick up the phone, and dial the appropriate number, without any
|
|
|
|
attempt to remember this number. You give the details of what you want
|
|
|
|
delivered. You wait for it to be delivered.
|
|
|
|
|
|
|
|
What's the difference, here? Well, there are several. First of all,
|
|
|
|
you have no idea what business you purchased your food from. Second,
|
|
|
|
your choice will be affected by the order in which the businesses are
|
|
|
|
listen in the directory, typically alphabetical, and not by previous
|
|
|
|
experience, food quality, or prices.
|
|
|
|
|
|
|
|
What on earth does this have to do with Perl?
|
|
|
|
|
|
|
|
Well, clearly you need to eat Pizza in order to code. Also, it just
|
2001-09-09 21:48:07 +04:00
|
|
|
struck me that, coincidentally, this is in fact a good metaphor for
|
|
|
|
the whole PLIF thing that someone mentioned earlier. See Table 1.
|
2001-05-05 11:12:56 +04:00
|
|
|
|
|
|
|
Real Life | Perl Program
|
|
|
|
--------------------+-----------------------------------------
|
|
|
|
Telephone Call | Perl Method Call
|
|
|
|
Ordering Pizza | Processing Data
|
|
|
|
Business | A Perl Module
|
|
|
|
Domino's Pizza | A Specific Perl Module
|
|
|
|
Pizza | The Method Call Return Value
|
|
|
|
Front Door | Where The Method Call Returns Its Value
|
|
|
|
Holiday | Unexpected Environment
|
|
|
|
Business Directory | A List Of Perl Modules
|
|
|
|
Deliveries | A Particular Perl Method In A Module
|
|
|
|
--------------------+-----------------------------------------
|
|
|
|
Table 1: A mapping of the real life example to the perl program
|
|
|
|
equivalent, in case the metaphor wasn't blindingly obvious.
|
|
|
|
|
|
|
|
Let's be more specific. Say you have a record ID, and you want to get
|
|
|
|
the data that it refers to out of the database. For simplicity, we
|
|
|
|
will assume that our database merely associates each number with a
|
|
|
|
string. So. In the Old World, you would do something like:
|
|
|
|
|
|
|
|
SendSQL("select string from data where id = $id");
|
|
|
|
my $string;
|
|
|
|
if (@row = FetchSQLData()) {
|
|
|
|
$string = $row[0];
|
|
|
|
} else {
|
|
|
|
$string = '';
|
|
|
|
}
|
|
|
|
# do something with $string...
|
|
|
|
|
|
|
|
That has some flaws: for example, what happens when you want to change
|
|
|
|
from SQL queries to QBE queries? What about if the fields in the
|
|
|
|
database change name?
|
|
|
|
|
|
|
|
Instead, what you want to do is delegate the task of querying the
|
|
|
|
database to some other module, known as a "data source", and merely
|
|
|
|
concern yourself with getting said data from the data source. To do
|
|
|
|
this, you first need to get a hold of the data source. The problem is
|
|
|
|
that you have no idea what data source to use -- do you want the
|
|
|
|
default SQL database data source or the default database QBE data
|
|
|
|
source? What about if neither of these exist, but someone will provide
|
|
|
|
a third type that you don't know about yet?
|
|
|
|
|
|
|
|
So instead, you merely ask a central controlling entity -- a registry,
|
|
|
|
or directory, of all known data sources -- for the data source that
|
|
|
|
deals with the default database. You then call predefined methods in
|
|
|
|
the data source. The code would look something like:
|
|
|
|
|
|
|
|
my $string = $app->getService('dataSource.default')->getString($app, $id);
|
|
|
|
# do something with $string...
|
|
|
|
|
|
|
|
There are several things to notice here. First of all, to get hold of
|
|
|
|
the data source we said:
|
|
|
|
|
|
|
|
$app->getService('dataSource.default')
|
|
|
|
|
|
|
|
That tells us that $app is the controller -- that is to say, the
|
|
|
|
central registry of all data sources is the main application
|
|
|
|
object. More on this later. It also tells us that the method used to
|
|
|
|
get the data source is called "getService".
|
|
|
|
|
|
|
|
You may be asking yourself why it is called "getService" instead of
|
|
|
|
the more obvious "getDataSource".
|
|
|
|
|
|
|
|
Well, data sources are not the only thing that you might want to get a
|
|
|
|
hold of. All the input and output is done using this technique -- so
|
|
|
|
that the main code doesn't need to know it's talking to IRC or over
|
|
|
|
HTTP to do its work. More on this later.
|
|
|
|
|
|
|
|
The general term for all these different interfaces is "services".
|
|
|
|
Hence, the name of the method is "getService" -- it gets the
|
|
|
|
appropriate service. I tried making it more obvious, but it was hard,
|
|
|
|
so I gave up. There are several other methods that return services,
|
|
|
|
and they are explained in the chapter describing the workings of the
|
2001-09-09 21:48:07 +04:00
|
|
|
application object, called "using get service" or some such.
|
2001-05-05 11:12:56 +04:00
|
|
|
|
|
|
|
You should also notice that getService() gets passed a string -- that
|
|
|
|
string is used to determine whether or not each registered module
|
|
|
|
provides the service or not. ("Providing a service" is called
|
|
|
|
"implementing an interface" in COM terms, I believe.)
|
|
|
|
|
|
|
|
The string is generally opaque, although that depends on the
|
|
|
|
module. What I mean by "opaque" is that modules don't try to parse it
|
2001-09-09 21:48:07 +04:00
|
|
|
to work out whether or not to claim to support a particular service,
|
|
|
|
they just do a straight string comparison with it.
|
2001-05-05 11:12:56 +04:00
|
|
|
|
|
|
|
The next thing to notice is that getService() returns an object, and
|
|
|
|
that it is therefore directly used as such -- the method on the data
|
|
|
|
source is invoked straight off the return value of the getService()
|
|
|
|
call, and it is the results of the getString() call on the service
|
|
|
|
that is stored in $string.
|
|
|
|
|
|
|
|
So, in summary: If you want to do something that might be done in
|
|
|
|
several different ways and the code you are immediately dealing with
|
|
|
|
doesn't need to know the difference, then you would implement the
|
2001-09-09 21:48:07 +04:00
|
|
|
"something" as a Service and use the getService() method on the
|
2001-05-05 11:12:56 +04:00
|
|
|
application object to get a reference to an instance of the service.
|
|
|
|
|
|
|
|
Questions raised by this:
|
|
|
|
1. How do you implement a service?
|
|
|
|
2. How do you use getService?
|
|
|
|
3. How do you get an application object?
|
|
|
|
4. How much should you tip the delivery guy?
|
|
|
|
|
|
|
|
We shall cover each of these questions, eventually. First, however,
|
|
|
|
I'm going to go on a totally different tangent because I am bored with
|
|
|
|
services now and what to talk about warnings and stuff.
|
|
|
|
|
|
|
|
|
|
|
|
______________________________
|
|
|
|
CHAPTER 3: PLIF ERROR HANDLING
|
|
|
|
| Wherein it is first claimed that PLIF has great tools for error
|
|
|
|
| handling but then that is shown to be totally untrue.
|
|
|
|
|
|
|
|
The root of (almost) every PLIF class is the "PLIF" class. What that
|
|
|
|
means is that at (almost) any point in PLIF-based code, you can use
|
|
|
|
methods that are part of the core PLIF class. Now, there aren't many
|
|
|
|
of them, so you'd better make the most of it!
|
|
|
|
|
|
|
|
The methods that are of interest to us right now are the following
|
|
|
|
five debugging aids:
|
|
|
|
|
|
|
|
dump(level, message)
|
|
|
|
Prints the message to standard error. The level argument is a
|
|
|
|
number, typically in the range of 0-9, stating the verbosity of the
|
|
|
|
message. Users of your application (as in, the people who install
|
|
|
|
it, not the people who use it on a daily basis) can change the
|
|
|
|
debugging level that is printed, so if you have a lot of
|
|
|
|
dump(9,'verbose debugging information') calls they can easily turn
|
2001-05-24 11:06:41 +04:00
|
|
|
them off. 0 is the most serious, 9 is the most trivial. Actually,
|
|
|
|
10 is the most trivial, but 10 is so trivial as to be unusable
|
|
|
|
unless you are trying to get a headache -- the core PLIF code calls
|
|
|
|
dump(10,'...') for almost every method call that goes through it.
|
2001-05-05 11:12:56 +04:00
|
|
|
|
|
|
|
warn(level, message)
|
|
|
|
Same as dump(), but includes a stack trace.
|
|
|
|
|
|
|
|
error(level, message)
|
|
|
|
Same as warn(), but raises an exception as well. (You can catch
|
|
|
|
exceptions using eval{}.)
|
|
|
|
|
|
|
|
assert(condition, level, message)
|
|
|
|
Calls error() if condition is true.
|
|
|
|
|
2001-05-05 22:28:08 +04:00
|
|
|
debug(message)
|
|
|
|
Same as dump(7, message). According to the code, level 7 is
|
2001-09-09 21:48:07 +04:00
|
|
|
"typical checkpoints (e.g. someone tried to do some output)".
|
2001-05-05 22:28:08 +04:00
|
|
|
|
2001-05-05 11:12:56 +04:00
|
|
|
notImplemented()
|
|
|
|
Calls error() with predefined arguments.
|
|
|
|
|
|
|
|
These tools are a great help. They should prevent you from ever
|
|
|
|
needing to use print() debugging, for instance. They allow you to
|
|
|
|
quickly wrap null pointer checks and the like in unobtrusive one
|
|
|
|
liners while supporting decent amounts of debugging information.
|
|
|
|
|
|
|
|
They also allow us to later reimplement the debugging code to add
|
|
|
|
better support for debuggers or pretty printing or mailing errors to
|
|
|
|
admins or whatever.
|
|
|
|
|
2001-05-24 11:06:41 +04:00
|
|
|
If you've been paying attention you'll notice there were actually six
|
|
|
|
debugging aids, and not five. This is just to demonstrate that they
|
|
|
|
will only actually help if you use them, not just if you look at
|
|
|
|
them. Clearly here I should have been using them if I wanted to catch
|
|
|
|
that fence-post error.
|
|
|
|
|
2001-05-05 11:12:56 +04:00
|
|
|
Unfortunately, using these utility methods to report errors can result
|
|
|
|
in suboptimal feedback to the user, and so should only be used to
|
|
|
|
report errors that you really were not expecting, such as missing
|
|
|
|
configuration files, errors sending mail, failures when connecting to
|
|
|
|
databases, and so on. For errors in user data, e.g. wrong password,
|
|
|
|
unknown requests, out of range input and the like, you want to report
|
|
|
|
the errors using the usual techniques of error codes and callbacks.
|
|
|
|
|
|
|
|
(Note. These debugging methods are _class methods_ and therefore you
|
|
|
|
do not need to ensure that $self is a reference before calling them.)
|
|
|
|
|
|
|
|
|
|
|
|
_________________________________
|
|
|
|
CHAPTER 4: IMPLEMENTING A SERVICE
|
|
|
|
| Wherein examples modules are provided on the grounds that they will
|
|
|
|
| enable the reader to learn how to create modules on their own, but
|
|
|
|
| with the knowledge that in practice the said examples will only be
|
|
|
|
| used for the purposes of copy and pasting.
|
|
|
|
|
|
|
|
Implementing a service is relatively easy. To demonstrate this, we
|
|
|
|
shall be implementing a "vendingMachine" service. First, we need to
|
|
|
|
define what we mean by a "vendingMachine" service, then we need to
|
|
|
|
define the API, and finally we shall implement it.
|
|
|
|
|
|
|
|
Concept Definition. You have to decide when you expect to use the
|
|
|
|
service -- in this case, it will be called by other parts of the
|
|
|
|
application when they need some food. The name of the service is
|
|
|
|
important. In this case, it's just a generic "vendingMachine", but
|
|
|
|
subtypes could include variants called "vendingMachine.drinks" or
|
|
|
|
"vendingMachine.sweets", for instance. One example of this in the PLIF
|
|
|
|
code is all the "dataSource.X" services, which all implement a basic
|
|
|
|
set of functionality that is used by other parts of the code when they
|
|
|
|
are passed a data source without knowning what it is.
|
|
|
|
|
|
|
|
API Definition. Now, having decided what we think the service is for,
|
|
|
|
we come to the second step, namely defining the API. This is just as
|
|
|
|
hard, and in my experience it takes a lot of attempts before you have
|
|
|
|
one you are happy with.
|
|
|
|
|
|
|
|
We're going to say that "vendingMachine" offers these methods:
|
|
|
|
|
|
|
|
insertCoins(amount)
|
|
|
|
Increases the amount of money assumed to be inside the vending
|
|
|
|
machine. Returns the result amount of cash.
|
|
|
|
|
|
|
|
selectSlot(slot)
|
|
|
|
Decreases the amount of money assumed to be inside the vending
|
|
|
|
machine and returns a string describing the product that occupied
|
|
|
|
the slot specified. Returns undef if there was not enough money.
|
|
|
|
|
|
|
|
refund()
|
|
|
|
Returns the amount of money in the machine, and sets it to zero.
|
|
|
|
|
|
|
|
Implementation. This is the fun part. Depending on the service, it can
|
|
|
|
also be the easiest.
|
|
|
|
|
|
|
|
I write my Perl modules in Emacs, so first I have a mode line:
|
|
|
|
|
|
|
|
# -*- Mode: perl; tab-width: 4; indent-tabs-mode: nil; -*-
|
|
|
|
#
|
|
|
|
|
|
|
|
Next comes the license, in this case MPL/GPL:
|
|
|
|
|
|
|
|
# This file is MPL/GPL dual-licensed under the following terms:
|
|
|
|
#
|
|
|
|
# The contents of this file are subject to the Mozilla Public License
|
|
|
|
# Version 1.1 (the "License"); you may not use this file except in
|
|
|
|
# compliance with the License. You may obtain a copy of the License at
|
|
|
|
# http://www.mozilla.org/MPL/
|
|
|
|
#
|
|
|
|
# Software distributed under the License is distributed on an "AS IS"
|
|
|
|
# basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
|
|
|
|
# the License for the specific language governing rights and
|
|
|
|
# limitations under the License.
|
|
|
|
#
|
|
|
|
# The Original Code is PLIF 1.0.
|
|
|
|
# The Initial Developer of the Original Code is Ian Hickson.
|
|
|
|
#
|
|
|
|
# Alternatively, the contents of this file may be used under the terms
|
|
|
|
# of the GNU General Public License Version 2 or later (the "GPL"), in
|
|
|
|
# which case the provisions of the GPL are applicable instead of those
|
|
|
|
# above. If you wish to allow use of your version of this file only
|
|
|
|
# under the terms of the GPL and not to allow others to use your
|
|
|
|
# version of this file under the MPL, indicate your decision by
|
|
|
|
# deleting the provisions above and replace them with the notice and
|
|
|
|
# other provisions required by the GPL. If you do not delete the
|
|
|
|
# provisions above, a recipient may use your version of this file
|
|
|
|
# under either the MPL or the GPL.
|
|
|
|
|
|
|
|
At last, some code! The first line is the Perl code saying what the
|
|
|
|
name of the package is:
|
|
|
|
|
|
|
|
package VendingMachine::Empty;
|
|
|
|
|
|
|
|
Hmm. It appears I've opted for implementing the Empty version of the
|
|
|
|
service. This ought the be fun. Next comes a bit of standard stuff:
|
|
|
|
|
|
|
|
use strict;
|
|
|
|
use vars qw(@ISA);
|
|
|
|
|
|
|
|
That's always there. "use strict" ensures that we avoid the worst of
|
|
|
|
ugly Perl, and "use vars" is required by the "use strict".
|
|
|
|
|
|
|
|
Next, we need to define what module we are inheriting from.
|
|
|
|
|
|
|
|
use PLIF::Service;
|
|
|
|
@ISA = qw(PLIF::Service);
|
|
|
|
|
|
|
|
All services must inherit from PLIF::Service or a descendant of that
|
|
|
|
module (e.g. VendingMachine::Empty!).
|
|
|
|
|
|
|
|
1;
|
|
|
|
|
|
|
|
This ensures that this module will return true. It's a Perlism.
|
|
|
|
|
|
|
|
Ok, finally the real meat. We have to claim that we provide the
|
|
|
|
vending machine service! This is done using a "provides" method:
|
|
|
|
|
|
|
|
sub provides {
|
|
|
|
my $class = shift;
|
|
|
|
my($service) = @_;
|
|
|
|
return ($service eq 'vendingMachine' or $class->SUPER::provides($service));
|
|
|
|
}
|
|
|
|
|
|
|
|
What this does is return true if the caller asked if we provide a
|
|
|
|
"vendingMachine" service, and otherwise it defers to the inherited
|
|
|
|
method. You'll notice this is a class method -- at this point, the
|
|
|
|
$class variable is probably a class and not necessarily an object.
|
|
|
|
|
|
|
|
Next we implement a constructor. (This is actually a method called by
|
|
|
|
the constructor. Just treat it like a constructor in other languages
|
|
|
|
and you'll be fine.) We need a constructor because we need to
|
|
|
|
initialise the amount of money to zero (as opposed to undefined).
|
|
|
|
|
|
|
|
sub init {
|
|
|
|
my $self = shift;
|
|
|
|
$self->SUPER::init(@_);
|
|
|
|
my($app) = @_;
|
|
|
|
$self->money(0);
|
|
|
|
}
|
|
|
|
|
|
|
|
Wowee, lots of PLIFisms there! Let's look at each one in turn. The
|
|
|
|
first line of the body sets the $self variable to be the reference to
|
2001-05-24 11:06:41 +04:00
|
|
|
the object. If you are familiar with JavaScript or C++, think "this".
|
2001-05-05 11:12:56 +04:00
|
|
|
|
|
|
|
The second line calls the inherited constructor with the same
|
|
|
|
arguments as was passed to _this_ constructor.
|
|
|
|
|
|
|
|
Speaking of which, the arguments are sorted out on the third
|
|
|
|
line. Most services will be given just one argument on construction,
|
|
|
|
namely a reference to the application. It is vital that services not
|
|
|
|
hold on to this! See the Weak References chapter for more details.
|
|
|
|
|
|
|
|
Finally, the fourth line is pure fun. Due to some magical fu described
|
|
|
|
in a later chapter, you can use the syntax shown to set a "field" of
|
|
|
|
the object to 0. You can also get the value using a call without any
|
|
|
|
arguments, as in "$self->money". More on this later.
|
|
|
|
|
|
|
|
Ok, so now we have to implement the methods that we claim to provide
|
|
|
|
by saying that we are a vending machine.
|
|
|
|
|
|
|
|
# Increases the amount of money assumed to be inside the vending
|
|
|
|
# machine. Returns the resulting amount of cash.
|
|
|
|
sub insertCoins {
|
|
|
|
my $self = shift;
|
|
|
|
my($money) = @_;
|
|
|
|
return $self->money($self->money + $money);
|
|
|
|
}
|
|
|
|
|
|
|
|
That method should be self-explanatory... First it sets $self, then it
|
|
|
|
sorts out the arguments (in this case just one, $money) and then it
|
|
|
|
uses the syntax described above to add $money to $self->money, which
|
|
|
|
it returns.
|
|
|
|
|
|
|
|
# Decreases the amount of money assumed to be inside the vending
|
|
|
|
# machine and returns a string describing the product that
|
|
|
|
# occupied the slot specified. Returns undef if there was not
|
|
|
|
# enough money.
|
|
|
|
sub selectSlot {
|
|
|
|
my $self = shift;
|
|
|
|
my($slot) = @_;
|
|
|
|
return undef;
|
|
|
|
}
|
|
|
|
|
|
|
|
The vending machine is empty, right? So that always return undef.
|
|
|
|
|
|
|
|
Finally, refund() -- lucky we are going to implement this, otherwise
|
|
|
|
people could never get their money back!
|
|
|
|
|
|
|
|
# Returns the amount of money in the machine, and sets it to zero.
|
|
|
|
sub refund {
|
|
|
|
my $self = shift;
|
|
|
|
my $money = $self->money;
|
|
|
|
$self->money(0);
|
|
|
|
return $money;
|
|
|
|
}
|
|
|
|
|
|
|
|
Ok! We have an implementation of a service!
|
|
|
|
|
|
|
|
In the next chapter we shall look at how to use it.
|
|
|
|
|
|
|
|
.############################## Everything above this line has
|
|
|
|
#################### BOOK MARK # already been sent to mozilla-webtools
|
|
|
|
'############################## in some form or another.
|
|
|
|
|
|
|
|
____________________________
|
|
|
|
CHAPTER 5: USING GET SERVICE
|
2001-09-09 21:48:07 +04:00
|
|
|
| Wherein the reader is introduced to the concept of magic and is then
|
|
|
|
| walked through the steps of taming the magic for his own purposes.
|
2001-05-05 11:12:56 +04:00
|
|
|
|
2001-09-09 21:48:07 +04:00
|
|
|
In Chapter 2, we learnt about services. It turns out that there is
|
|
|
|
more than one kind of service.
|
|
|
|
|
|
|
|
The Plain Old Service - what was described in Chapter 2. There is
|
|
|
|
one instance of each plain old service. If two parts of the
|
|
|
|
codebase both ask for a particular service, they get given the same
|
|
|
|
instance. The same instance of a plain old service is used for the
|
|
|
|
lifetime of the application.
|
|
|
|
|
|
|
|
The Service Instance - an instance of a service created especially
|
|
|
|
for the requester, and not cached. The lifetime of a service
|
|
|
|
instance is typically very short.
|
|
|
|
|
|
|
|
The Object - an instance of a service that is create by one service
|
|
|
|
and added to the list of objects. The lifetime of an object is well
|
|
|
|
defined. All services that request objects providing a particular
|
|
|
|
service will be given the same instance(s).
|
|
|
|
|
|
|
|
Each of these has an associated "get" method on the controller.
|
|
|
|
|
|
|
|
getService(name)
|
|
|
|
Returns the instance of the first service found providing
|
|
|
|
"name". The service's constructor will be called with one argument,
|
|
|
|
a reference to the controller, which must not under any
|
|
|
|
circumstances be held onto.
|
|
|
|
|
|
|
|
getServiceInstance(name, arguments)
|
|
|
|
Returns a new instance of the first service found providing
|
|
|
|
"name". The constructor will be passed a reference to the
|
|
|
|
controller followed by the "arguments" parameter.
|
|
|
|
|
|
|
|
getObject(name)
|
|
|
|
Returns the instance of the first registered object found providing
|
|
|
|
"name" as an object service.
|
|
|
|
|
|
|
|
In addition to the first qualifying service or object, one can also
|
|
|
|
retrieve the list of all qualifying services or objects. The two
|
|
|
|
methods available to do this are:
|
|
|
|
|
|
|
|
getServiceList()
|
|
|
|
Returns a list containing instances of all the services found
|
|
|
|
providing "name". The services' constructors will be called with
|
|
|
|
one argument, a reference to the controller, which must not under
|
|
|
|
any circumstances be held onto.
|
|
|
|
|
|
|
|
getObjectList()
|
|
|
|
Returns a list containing the instances of all the registered
|
|
|
|
objects found providing "name" as an object service.
|
|
|
|
|
|
|
|
A convenient way of using these lists is through Magic Arrays. Magic
|
|
|
|
arrays are array references that act as normal objects. The easiest
|
|
|
|
way to explain these is by example:
|
|
|
|
|
|
|
|
my @languages = $app->getCollectingServiceList('example.text')->language;
|
|
|
|
|
|
|
|
Pretty simple looking, huh. But that one line does a lot of work.
|
|
|
|
Let's expand the example to two lines and then study each bit in turn:
|
|
|
|
|
|
|
|
my $magicArray = $app->getCollectingServiceList('example.text');
|
|
|
|
my @languages = $magicArray->language;
|
|
|
|
|
|
|
|
The first line returns a Collecting Magic Array of all the services
|
|
|
|
that are registered and claim to provide the "example.text" service.
|
|
|
|
This works just like the getService() method, except that instead of
|
|
|
|
just finding and returning the first match, it finds, instantiates and
|
|
|
|
returns all the matches (like getServiceList()) wrapped in a
|
|
|
|
Collecting Magic Array (unlike getServiceList()).
|
|
|
|
|
|
|
|
So where's the magic? Well, that's what the second line shows us.
|
|
|
|
Imagine if you will that the "example.text" service is defined as
|
|
|
|
having a "language" property that is a single string. If you wanted to
|
|
|
|
get the list of all the values of the "language" property as returned
|
|
|
|
by each service in your service list, you would have to use some sort
|
|
|
|
of "foreach" loop... or, you could just call the method on the magic
|
|
|
|
array, which then forwards the call to each of the services and
|
|
|
|
collects the return values into one long list (whence the name).
|
|
|
|
|
|
|
|
There are three different types of Magic Arrays.
|
|
|
|
|
|
|
|
Collecting - Calls each service in turn, and returns a list
|
|
|
|
containing the concatenated results of all the calls.
|
|
|
|
|
|
|
|
Piping - Calls each service in turn, and returns a list with each
|
|
|
|
item being a reference to the array which was returned for the
|
|
|
|
respective service.
|
|
|
|
|
|
|
|
Selecting - Calls each service in turn until one returns a defined
|
|
|
|
value, and returns that value. (Note: always executes the method
|
|
|
|
calls in an array context, and then returns the first value in a
|
|
|
|
scalar context.)
|
|
|
|
|
|
|
|
There are six methods on the controller ($app) that return magic
|
|
|
|
arrays. They are:
|
|
|
|
|
|
|
|
getCollectingServiceList()
|
|
|
|
getCollectingObjectList()
|
|
|
|
getPipingServiceList()
|
|
|
|
getPipingObjectList()
|
|
|
|
getSelectingServiceList()
|
|
|
|
getSelectingObjectList()
|
|
|
|
|
|
|
|
The get*ServiceList() methods act just like getServiceList() but
|
|
|
|
return the appropriate magic array instead of a list, and the
|
|
|
|
get*ObjectList() methods similarly return the appropriate magic array
|
|
|
|
primed with what getObjectList() would return.
|
|
|
|
|
|
|
|
|
|
|
|
As you may have noticed in the descriptions of the methods above,
|
|
|
|
service constructors get passed different arguments depending on
|
|
|
|
exactly what type of service they are.
|
|
|
|
|
|
|
|
Normal services have the lifetime of the $app, and therefore can be
|
|
|
|
created from any random part of the application. For this reason,
|
|
|
|
there is no way of choosing a particular set of arguments for the
|
|
|
|
constructor, and so a simple convention has been picked: the only
|
|
|
|
argument is the $app reference. (NOTE: services must not hold a
|
|
|
|
reference to the $app object! If they do, there will be a circular
|
|
|
|
ownership model and the services and the application will never get
|
|
|
|
freed. See chapter 7, "Weak References".)
|
|
|
|
|
|
|
|
Service Instances, on the other hand, are created on a per-request
|
|
|
|
basis, and therefore the time of construction is very well defined.
|
|
|
|
They can be passed particular arguments by passing the relevant
|
|
|
|
arguments to the getServiceInstance() method.
|
|
|
|
|
|
|
|
Objects are inserted into the object list using the addObject()
|
|
|
|
method, and therefore construction is out of the control of the $app
|
|
|
|
and so no firm rules can be said about passing arguments to object
|
|
|
|
constructors.
|
2001-05-05 11:12:56 +04:00
|
|
|
|
|
|
|
__________________________________
|
|
|
|
CHAPTER 6: THE MAGIC OF PROPERTIES
|
|
|
|
| Wherein it is admitted that the last description of the PLIF class
|
|
|
|
| was incomplete and was missing some rather important facts.
|
|
|
|
|
|
|
|
propertyGet, propertySet, and friends.
|
|
|
|
|
|
|
|
__________________________
|
|
|
|
CHAPTER 7: WEAK REFERENCES
|
|
|
|
| or, Why The $app Variable Is Passed Religiously From Service To
|
|
|
|
| Service Without A Thought To Caching It and Why It Would Be Bad To
|
|
|
|
| Do Otherwise.
|
|
|
|
|
2001-05-05 22:28:08 +04:00
|
|
|
You no copy you go boom boom and other stories of the lack of Perl 5.6
|
|
|
|
on the author's development machine.
|
2001-05-05 11:12:56 +04:00
|
|
|
|
|
|
|
______________________________________
|
|
|
|
CHAPTER 8: THE MAIN APPLICATION OBJECT
|
2001-09-09 21:48:07 +04:00
|
|
|
| Wherein a family of methods is brought to the front and examined as
|
|
|
|
| if for a college entrance exam, resulting in the discovery that one
|
|
|
|
| of the methods is not very bright.
|
2001-05-05 11:12:56 +04:00
|
|
|
|
|
|
|
Or not.
|
|
|
|
|
|
|
|
___________________________
|
|
|
|
CHAPTER 9: INPUT AND OUTPUT
|
|
|
|
| Wherein the magic of $app->input and $app->output is explained.
|
|
|
|
|
|
|
|
Some day.
|
|
|
|
|
2001-09-09 21:48:07 +04:00
|
|
|
_________________________________
|
|
|
|
CHAPTER 10: THE SERVICE REFERENCE
|
|
|
|
| or, what does what do, and how?
|
|
|
|
|
|
|
|
You have _got_ to be kidding.
|
|
|
|
|
2001-07-26 03:54:32 +04:00
|
|
|
___________________________
|
2001-09-09 21:48:07 +04:00
|
|
|
CHAPTER 11: COMMON MISTAKES
|
2001-07-26 03:54:32 +04:00
|
|
|
| Wherein perls of wisdom are given out in order to save the reader
|
|
|
|
| some time.
|
|
|
|
|
|
|
|
If you get an error message of the form:
|
|
|
|
|
|
|
|
Can't locate object method "myMethod" via package "a.service.name" at SomePath/SomeModule.pm line 42
|
|
|
|
|
2001-09-09 21:48:07 +04:00
|
|
|
...then you are probably calling getService() on the $self object
|
2001-07-26 03:54:32 +04:00
|
|
|
instead of the $app object. The error happens because
|
|
|
|
|
|
|
|
$aPLIFObject->getService('a.service.name')->myMethod();
|
|
|
|
|
|
|
|
...results in |$aPLIFObject->{'a.service.name'}| being set to
|
|
|
|
'a.service.name' and returns that exact value, which then results in
|
|
|
|
the method call being invoked on the string, as in:
|
|
|
|
|
|
|
|
'a.service.name'->myMethod();
|
|
|
|
|
2001-09-09 21:48:07 +04:00
|
|
|
...which of course will fail, since the package "a.service.name"
|
2001-07-26 03:54:32 +04:00
|
|
|
doesn't exist and thus doesn't have a method called myMethod().
|
|
|
|
|
|
|
|
For the same reason, this error can happen if you misspell the name of
|
|
|
|
the service getter method (e.g., if you use |$app->getServiceList()|
|
|
|
|
instead of |$app->getCollectingServiceList()|).
|
|
|
|
|
2001-09-09 21:48:07 +04:00
|
|
|
Another common mistake is tipping the delivery guy $200 for a single
|
|
|
|
pizza. Ok, it's not a common mistake. However, it is a serious
|
|
|
|
mistake. Don't do it.
|
|
|
|
|
2001-05-05 11:12:56 +04:00
|
|
|
_____________________
|
|
|
|
CHAPTER n: CONCLUSION
|
2001-09-09 21:48:07 +04:00
|
|
|
|
2001-05-05 11:12:56 +04:00
|
|
|
| Wherein it is revealed that all is subject to change, only available
|
|
|
|
| while stocks last, and void where prohibited by law.
|
|
|
|
|
|
|
|
The End.
|