04029437
m2.45
using complex data types
. The naming convention for these is uppercase with underscore
word separators. For example:
$SOME_GLOBAL_VAR = 100
.
To access global variables from within a function or class method we will use the
global
key word. Note we do not have to do this with constants because they are automatically global.
We could use the
$_GLOBALS
array but this does not provide a very clear way of accessing
global variables. Note that all variables defined in the global space are technically global. The
example below shows how we would access
$SOME_GLOBAL_VAR
from within a function.
function foo($value) {
global $SOME_GLOBAL_VAR;
return (int)$value * $SOME_GLOBAL_VAR;
}
As a side note, PHP 5 supports namespaces; we however, will not use these for two
reasons. (1) It makes differentiating between our JSON-RPC namespaces and the
application implementation ambiguous. (2) The application does not use vast numbers
of classes, interfaces, files or sets of functionality. Hence we do not require the use of
PHP 5 namespaces.
The
namespaces
folder contains all of the supported JSON-RPC
namespaces
. Every
namespace defined here must include a
helper.php5
file. This file must contain a class
that implements the
NamespaceHelper
interface. The class is named
MynamespaceHelper
,
for example the namespace
foo
would define the class
FooHelper
. Beware: PHP 5 class
names are case sensitive
.
The
suggest
folder is included to indicate the location of this namespace. As far as the
application is concerned it only need be aware of the
SuggestHelper
class, because this
class will handle the implementation of the
suggest
namespace.
system
on the other
hand, does not require any additional files, all of the functionality provided by this
namespace is encapsulated in the
SystemHelper
class.
This brings us neatly to the next area of the application design. We need to address how
we are going to implement the
suggest
namespace. At the root of the namespace is the
helper class
SuggestHelper
, all calls to the namespace are made through this classes
static
executeProcedure()
method. Since we must define the
hasProcedure()
method,
we can assume that all incoming requests via the
executeProcedure()
method are calling
a valid procedure.
In the class
SuggestHelper
we will implement a corresponding private static method for
each procedure. These methods will validate the incoming parameters, ensuring the
data types and values adhere to the schema specification. If the parameters are not valid,
a suitable exception will be thrown.
All exceptions thrown while executing a procedure in any namespace must be
accompanied by the suggest error value
5
, see Table 6 for details.
We can split the procedures into two groups, source specific, and non-source specific.
getVocabularies
is the only non-source specific procedure. This procedure will be
handled solely in the helper class. The remaining procedures will use source handlers.
Every source will be required to implement a handler class that implements the common
interface
SourceHandler
. This interface will allow each and every source to implement its
own mechanism of responding to requests.
By using a separate source handler for each source, we are making the prototype
modular. The modularity will allow the system to host numerous sources, as specified
by the schema, and those sources need not be related in any way. For example we could
