thekid/rfc — Issue #69: RFC 0069: Basic EASC server in PHP
Author: thekid
Created: 2011-10-09 14:49:50+00:00
State: open

Scope of Change
====
An EASC server implementation will be written in userland PHP.

Rationale
====
Testing.

Functionality
====

Featureset
----
The following features will be included in the first release:

```
* EJB3-style stateless session beans
* Resource injection (rbms connections, logger categories, properties)
* Hot deployment

```

The following features will not be included in the basic version:

```
* Authentication and protection
* Other bean types
* Messaging
* Transactions
* AOP / Interceptors

```

Beans
----
Beans - that is: classes following a certain standard in order to be
recognized by the application server as services - are plain XP classes
(meaning they extend lang.Object) decorated with annotations.

The following rules apply:

```
* The class annotation @bean denotes this class is a bean class.
* Any method that should be invokeable via remote method invocation
is decorated with the @remote annotation

```

Example:

```php
cat= $cat;
}
}
?>
```

The bean class does not need to implement any interfaces or extend any
classes other than lang.Object.

The @inject annotation
----
This annotation marks methods as resource injectors.

```
* Resources are one of the following: database connections, logger
categories, properties.

* Resources are configured by property objects:
- The property manager's lookup path is set to "etc/" per default
and may be set via xpcli -c
- The connection manager is configured by database.ini
- The logger is configured by log.ini

```

1) Injecting database connections

```php

```
This method will receive a DBConnection instance (via
ConnectionManager::getInstance()->getByHost('news', 0))

2) Injecting logger categories

```php

```
This method will receive a LogCategory instance (via
Logger::getInstance()->getCategory('default'))

3) Injecting properties

```php

```
This method will receive a LogCategory instance (via
PropertyManager::getInstance()->getProperties('app'))

Packaging
----
In order to deploy beans they will have to packaged by a packaging tool.
This tool creates the remote interface and a XAR (XP Application Archive)
the latter of which can then be deployed in the server.

The XAR contains the following:

* A property file (META-INF/bean.properties)
Contains the bean class' name, type, remote interface and the name to
which to bind it to.

```
class="net.xp_framework.beans.stateless.RoundtripBeanImpl"
remote="net.xp_framework.beans.stateless.Roundtrip"
type=STATELESS
lookup="xp/demo/Roundtrip"

```

* The remote interface
An interface generated from the bean class, to be used by both client
and server (via proxies).

This name is derived by concatenating the bean class' package and the
bean name's basename (from @bean.name).

For the above example, assuming RoundtripBean's fqcn is
net.xp_framework.beans.stateless.RoundtripBean, the remote
interface would be named net.xp_framework.beans.stateless.Roundtrip.

* The bean class' implementation
A class that extends the bean class and implements the remote interface

```php

```

* Additional resources required by the bean. These can be retrieved
by the classloader's getResource() method.

* The following special property files, optional:
- etc/log.ini
If present, the logger will be configured with this file

- etc/database.ini
If present, the connection manager will be configured with this file

Logger configuration example
----

```
[default]
appenders="util.log.FileAppender"
appender.util.log.FileAppender.params="filename"
appender.util.log.FileAppender.param.filename="/var/log/xp/bean-%Y-%m-%d.log"

```

Database configuration example
----

```
[vod]
dsn="mysql://user:password@localhost/VOD?autoconnect=1"

[changeblog]
dsn="mysql://serendipity:********@localhost/serendipity?autoconnect=1"

```

Deployment
----
The server will support deployment by means of copying the XAR packages
to a "deploy" directory, which the server monitors by scanning for new
or touched files periodically, deploying as needed. In order to differ beans
from normal XAR library packages, archives containing deployable beans end with
".bean.xar." Normal XAR archives found in the "deploy" directory will only be
added to the php inlude path.

Resources
----
The server will support a set of configuration files stored in a "etc"
directory. Additionally, resource configurations for database connections, ldap
clients etc will reside in "etc/env". The server will hold the configured
resources globally for all beans.

Security considerations
====
n/a

Speed impact
====
n/a

Dependencies
====
- xp-framework/rfc #65
Server Protocol API (implemented)

Related documents
====
- http://experiments.xp-framework.net/?arena,peking
Experiment

- https://glassfish.dev.java.net/
Glassfish: Open Source Java EE 5 Application Server

Comments
====
- friebe, Wed Aug 23 18:09:21 CEST 2006
Side note: The @remote annotation could replace the @webmethod
annotation for SOAP, XMLRPC, JSON, etc. But maybe we should
wait for the "super unified remote services RFC":)

- friebe, Fri Aug 25 14:07:15 CEST 2006
Fixes to the ArchiveClassLoader class have been made in order
to support classes in XARs using other classes from the archive.
This functionality is verified by the ArchiveClassLoaderTest
unittest.

- gelli, Mo Dez 11 17:20:58 CET 2006
Added some info concerning the resources management and deployment
of beans and libraries.