Units; The Fundamentals
Xua Server
Xua generates three projects. Xua Server, Marshal Library, and Documentations. Among these projects, the server is the most important one, which contains all the units that serve logic to the whole project. The role of the server is to be an interface between the front-end application and the database. The server is responsible for reading and modifying the database based on the requests it receives.Xua Server Directly Defined Units
There are some units in the server project that need a direct definition from the programmer. These units are shown in blue on the architecture page.Universal Resources Pool
A Xua Server contains a pool of resources that are available for use. These resources can be available universally, i.e., foreign parties can use resources, and internally, i.e., available for internal resources and units. The idea is similar to a class's private and public visibility, but a public class is only accessible from other codes on the same project, while a universal resource is accessible from other projects, even on other machines other than where the server project is stored. Xua resources are divided to Methods, Entities, Supers, Services, and Public Resource Files.Methods are the central part of a Xua Project. A method is a minimal unit that does a particular job when called. One can think of methods as just functions, but there are two differences. A method can be called from outside of the project and can return multiple values.
Methods are simply triplets $M = (Q, R, B)$. The first member,
Request, shown by $Q$, defines the structure of request that needs to be prepared and given to the method, and the second one, Response, shown by $R$, defines the structure of response that the method returns. The third member, Body, shown by $B$, is a script executed when the method is called.Xua will generate a PHP class indirectly extending a Xua abstract class called
MethodEve for each Entity Block the programmer creates. One can call these Method classes using their constructor. For example$response = new SomeMethod($request);
is a PHP script that calls
$SomeMethod with request $request provided and stores the result in $response.A Xua project can communicate with a database server (usually MySQL), but the programmer must specify the database structure. To do so, Xua offers Entity Blocks. Xua will generate a PHP class extending a Xua abstract class called
Entity for each Entity Block the programmer creates. These Entity classes are in a one-to-one correspondence with database tables. Each row of the table then can be corresponded by an instance of the table’s corresponding class.To define an Entity, the programmer needs to define a list called
Fields containing Entity columns with their types. Setting the Fields is mandatory, but there are some optional members an Entity may have.One member is a list called
Indexes, which defines the database indexes, that would make select queries faster or force unique values (Read more about database indexes by googling).Another is a boolean function (predicate) called
Validation, which checks if an Entity instance (a row) is valid according to business logic (part of the program that encodes the real-world business rules that determine how data can be created, stored, and changed). For example, assume we have two fields, country and city in the Entity User. The Validation function is responsible for checking if the city is inside the country and avoid invalid or inconsistent data.Therefore, an Entity is theoretically a triplet $E = (F, I, V)$. Although one can override database communication methods (functions responsible for reading or modifying data), that is a technical detail, and we do not cover it in this section.
Super Types or simply Supers are parametric types.
Let us talk about types first. One can think of a type as a set, for example the type
Integer is actually the set $\mathbb{Z} = \{0, 1, -1, 2, -2, \dots \}$ and when we say that $42$ is of type Integer, this means that $42 \in \mathbb{Z}$, which is written $42 : \mathbb{Z}$ in Xua's syntax.
We know that there is a one-to-one correspondence between sets and predicates. Having a predicate $P$, we can define the corresponding set to be $S = \{ x | P(x) \}$, and having a set $S$, we can define the corresponding predicate to be $P(x) := x \in S$. Since implementing predicates as boolean functions is more practical in computers, we use predicates to define types.However, there are some features that types usually have that sets do not. In Xua's definition of type, a type is a set equipped with three functions
NativeType, Marshal, and Unmarshal. We express a type by the 4-tuple $(P, Y, M, U)$, where $P$ is the characteristic function of the type's set. These functions make a type dependent on the target language. For example, if we are willing to use the integer type in Java language, we need to write these functions in Java language.Note that predicate can only be defined in the PHP language. But others are stack-based, meaning that they can be written in any of Xua's supported languages and also for the database.
The Native Type function must return a string literal declaring the value type in the native language's syntax. For example, if the type accepts date-times and null value, it must return
?DateTime for PHP language and DATETIME NULL for MySQL.Note. The database functions are written on PHP syntax, for example, for the MySQL Native Type one can write
Type<Database>{
return "DATETIME NULL";
}
The Marshal and Unmarshal functions are responsible for preparing the values for transmitting or storing. To store a value in the database and read from it, one must write marshaling functions with the database as the target, and for transmitting over the HTTP, PHP and front-end languages are used as the target.
As an example (that is not quite practical and efficient), let $T$ be the type of integers defined for the MySQL stack. We know $P(42)$ is true; therefore, we can say $42 : T$. It seems that $M$ must be $U^{-1}$, but it is not a necessity. Let us say that $M$ takes an integer and returns its binary representation. Therefore $M(42) = '101010'$. The $U$ must be the opposite, so $U('101010') = 42$, but what is $U('42')$, the decimal representation in a string. Can we say this is undefined and the domain of $U$ only accepts binary strings? It is up to the programmer that $U = M^{-1}$ or not, so the programmer needs to define both $M$ and $U$ functions separately. Finally, we can say $T$ must return the string
VARCHAR(100). Because the result of our marshal function is a string, and Xua uses that to store data in the database.Now, what is a Super Type? A Super Type is a function that takes some parameters and returns a type (Actually returns a list of types for different stacks). A Super Type is an object a whole level above a type. Each Super Type eventually results in a PHP class extending a Xua abstract class called
Super. Each instance of this class is a type (possible to use different stacks on it), and the class constructor is the function that takes some parameters and creates a type. The parameters are then accessible as attributes. For example, take a look at Enum that takes one parameter called values.$genderType = new Enum([
'values' => ['male', 'female']
]);
The parameter
values is set to array ['male', 'female'] and the variable $genderType is now a type that has the 4 discussed members.$P$, the first member, is called
accepts.var_dump($genderType->accepts('male')); \\ dumps true
Since $\mathsf{male} \in \{\mathsf{male}, \mathsf{female}\}$.
Now note that for the stack-based functions, the server project includes only two stacks, database, and PHP. Functions for other stacks are included in the corresponding Marshal Libraries.
So there must be two $Y$'s, in the PHP generated class. The database-targeted function is called
databaseType, and the PHP-targeted function is called phpType.var_dump($genderType->databaseType()); \\ dumps 'INT'
var_dump($genderType->phpType()); \\ dumps 'int'
Similar to Native Type, there are two $M$s
marshal and marshalDatabase, but for simplicity assume they obey the same algorithm, which is returning the index of the element in array values.var_dump($genderType->marshal('male')); \\ dumps 0
var_dump($genderType->marshal('female')); \\ dumps 1
At last, $U$ functions
unmarshal and unmarshalDatabase.var_dump($genderType->unmarshal(1)); \\ dumps 'female'
Note. The marshal and unmarshal functions of Xua's official Enum are both the identity function; this is just an example.
There is also another member of a type that returns the parameters given to it when constructed.
$genderType->parameters();
Will return the following map.
[
'value' => ['male', 'female']
]
A Little Formalism on Super Types
The set of boolean values, i.e., $\{\mathsf{0}, \mathsf{1}\}$ is shown by $\mathbb{B}$.The set of all single-argument predicates is shown by $\mathbb{P}$, all Native Type functions by $\mathbb{Y}$, all marshal functions by $\mathbb{M}$, and all unmarshal functions by $\mathbb{U}$.
The set of all types (the so-called 4-tuples) is shown by $\mathbb{T}$.
A simple observation is that $\mathbb{T} = \mathbb{P} \times \mathbb{Y} \times \mathbb{M} \times \mathbb{U}$.
A Literal Name is a literal string containing only alphanumeric characters, starting with a lowercase character. The set of all Literal Names is shown by $\mathbb{L}$.
The set of all values possible to store in a variable is shown by $\mathbb{X}$.
A Dictionary is a partial function $D: \mathbb{L} \to \mathbb{X}$ and is usually expressed by all of its records. The set of all dictionaries is shown by $\mathbb{D}$.
For example, Let $D$ be a dictionary with domain $\{\mathsf{name}, \mathsf{gender}\}$, $D(\mathsf{name}) = \mathsf{Kamyar}$, and $D(\mathsf{gender}) = \mathsf{male}$. We can express $D$ as
{name: 'Kamyar', gender: 'male'}.The set of all stacks (PHP, Database, Dart, JS, Java, etc.) is shown by $\mathbb{K}$.
So we can formally say that a Super is a function $S: \mathbb{K} \times \mathbb{D} \to \mathbb{T}$.
But we technically define a super to be the 5-tuple $\mathfrak{S} =(\mathfrak{P}, \mathfrak{Y}, \mathfrak{M}, \mathfrak{U}, \mathfrak{V})$, where $\mathfrak{P}: \mathbb{D} \to \mathbb{P}$, $ \mathfrak{Y}: \mathbb{K} \times \mathbb{D} \to \mathbb{Y}$, $ \mathfrak{M}: \mathbb{K} \times \mathbb{D} \to \mathbb{M}$, $ \mathfrak{U}: \mathbb{K} \times \mathbb{D} \to \mathbb{U}$, and finally $ \mathfrak{V}: \mathbb{D} \to \mathbb{B}$ (We discuss the $\mathfrak{V}$ later). The correspondence is the following.
\begin{eqnarray*}
\begin{cases}
S(K, D) = (\mathfrak{P}(D), \mathfrak{Y}(K, D), \mathfrak{M}(K, D), \mathfrak{U}(K, D)) & \mathfrak{V}(D) \\
S(K, D) \textit{ raises error} & \neg \mathfrak{V}(D)
\end{cases}
\end{eqnarray*}
As one can see above, the Validation part of a Super $\mathfrak{V}$ is responsible for validating the given arguments.
some data-types are more than an entity or a Super. Some classes like
DateTime are neither in an equivalence relation with a database table nor possible to implement with Xua's Super, since the programmer may need methods such as addDays, format, or toJalali from this data-type.Also, some procedures need to be implemented somewhere other than Methods, Supers, or Entities. For example, adding a watermark to an image or building a PDF.
Xua satisfies this need by letting programmers write their native PHP scripts. Although the codes must be written inside classes, the programmer is pretty much free to do everything inside the classes. The Xua engine will copy these native codes to the resulting project as they are.
Resource Files
In almost any project, there exist some files that are not native scripts; these files can be anything, assets, user-uploaded files, documents, etc. In Xua's terminology, we call any non-executable file a resource file. The resource files exist directly in the resulting project directory, and the programmer must mark the directories that contain resource files as resource directory inconfig.json. Read Configurations Chapter to see how to do this.Public Resource Files
Resource files can be public, i.e., accessible by just going to the file's address. For example, when a user opens a web page in the browser, there are some assets, e.g., styles, fonts, images, etc., that browser fetches from the server. These files must be marked as public.Private Resource Files
In many projects, some files are needed to be on the server but are not public files. For example, think of an online book store. There are many.pdf files on the server which the server sends them via email or shows them on the web only if the user is authorized and paid for them. These files must be marked as private.interfaces are the frontline of the project, immediately executed when a user requests on the interface's defined route. We usually avoid writing codes that include business logic; instead, we call a resource responsible for the route. Since we have a specific route called URPI that handles all the direct requests for resources, writing a new interface is only helpful in rendering a website, i.e., we define routes for pages the user visits, and ask a resource (a Method resource) to create an HTML page, and show the page created to the user.
Xua Server Generated Units
some units exist in the server project that are entirely generated by the Xua engine, and there is no need for a programmer to modify them, but it helps if the programmer knows how they work, and in some cases, the programmer may modify them in a way that is more suitable for the project.Universal Resources Pool Interface (URPI)
Accessing resources on the same project is as easy as before; one unit can call a resource internally, and there is no complexity. Although accessing a resource from other machines needs a protocol, the client needs to marshal the request in a data-type that is available for transmitting on the network, then we need to unmarshal the request in a way that is meaningful for Universal Resource Pool, this is done by a predefined interface called URPI. The client tells URPI what resource is needed, URPI calls the resource, prepares the result for network transmitting, and sends the result back to the client, where the result can be unmarshalled and used.Note. The URPI is an Interface existing in the interfaces directory of the template project. The URPI is a Xua source file, meaning it is not generated when building the project; it has been generated only once when making a new project from Xua's default template. Therefore this unit is modifiable and even removable.
Route Detection Unit
The programmer can map URIs on the website to interfaces using a file calledroutes.xrml (Xua's routes minimal language). This way, when a user or client sends a request to the server, it is the job of RDU to detect which route matches the requested URI and method (such as POST, GET, OPTIONS, etc.). After the route is detected, Xua will call the corresponding interface, and then the script inside that interface returns the desired response.There is also a predefined service called
RouteService, which has a function that does the inverse of this mapping and helps find the URI of an interface.Xua Exception Handler
After the interface returns the response, it is not prepared to show to the user yet. Immediately after interface code execution, the result goes to the XEH, any uncaught exception, fatal error, warning, etc. get caught here, and a default error page is shown to the user in order to avoid inside script or data leaks, as well as making the website more user friendly.It is possible to modify how Xua catches exceptions by modifying a predefined service called
ExceptionService. For example, one may want to make it possible for developers to see the exact error while users must see a simple error page. Alternatively, one may want to show an error message in JSON instead of showing an HTML page. In these cases or other similar cases, One can modify ExceptionService and check if the request is sent by a developer, for example, by checking a special header. Read ExceptionService for more practical information.The Marshal Library is a client library that can be built in several front-end languages. The library helps the front-end developers to access resources from the Universal Resources Pool. For example, if there is a method in the pool called
Method\Media\GetOne, the front-end developer can call it using the following code in Dart.result = Marshal.Method.Media.GetOne(mediaId);
The Marshal library sends a request to the server saying the method
Method\Post\Get needs to be executed with given marshaled parameters. The URPI then unmarshals the given parameters, calls the method, receives the response, marshals it, and sends it back to the client. The Marshal library fetches it, unmarshals it, and returns the structured response, which then will be used in the front-end project.Virtual Resource Pool
The Virtual Resource Pool is a set of methods and entities, twins of the ones in the server, containing only a server call and nothing more.Entity Interfaces
For each entity on the server project, a twin entity exists inside VRP but with hollow methods. Each method only contains an HTTP request that tells the server to execute its twin; the result is fetched from the server and is returned.Method Interfaces
For each method on the server project, a twin method exists inside VRP but with a hollow body. The body only contains an HTTP request that tells the server to execute its twin; the result is fetched from the server and is returned.Server Service Classes discussed above are classes that programmers may use to instantiate objects. These objects can be used in universal resources. For example, a method may return an instance of a service class. Xua marshals the result and sends it to the Marshal Library where it should be unmarshalled. But how are we going to represent the object there? Assume we have a method called
getNow, and the method responses the variable now, an instance of DateTimeService. Then in the JS project, we want to get the Jalali representation of the DateTimeService using the method formatJalali on DateTimeService. This is not something we ask the server to do for us. We should be able to execute the method on the client side. Therefore, if we want to use some methods of some service classes on the client side, we should rewrite the class in the native language of the client side. The programmer can write native codes for the client, and the codes are copied to the Marshal Library when building.Marshal Library Generated Units
Just as the server project, some units exist in the Marshal library that are entirely generated by the Xua engine, and there is no need for a programmer to modify them, but it helps if the programmer knows how they work, and in some cases, the programmer may modify them in a way that is more suitable for the project.Marshal/Unmarshal Unit
This is the unit that the library derived its name from. This unit is responsible for marshaling request data and unmarshaling the response. The unit is affected by supers definitions but is not directly programmable.Http Connection Unit
This is a rather technical unit that sends requests to the server and fetches responses. This unit can also modify requests and responses, for example, adding a user token, API key, etc., to the request. This unit is possible to modify. The programmer must modify a predefined service calledHttpConnectionService. Read HttpConnectionService for more practical information.Xua is capable of generating a set of documentations for the project. Currently, the documentations are available in HTML and LaTeX formats. Xua engine uses comments inside project source files to generate the doc. The current documentation you are reading is generated by Xua, and all these texts are just comments inside source files.
The documentations are file-to-file, meaning that for each source file, there exists a
.html or .tex file and vice versa.Service Classes Documentations
Service classes are the files labeled as services inconfig.json, and are only project source files without the .xua extension. For each of these files, the Xua engine generates a documentation file consisting of the comments.Super Types Documentations
Other than including the comments in the documentation, Xua can automatically generate a table of super parameters, with their types, default values, and description. The description of a parameter is the comment that comes immediately after the parameter definition; if no comment is found, the description is set to-. Xua can also sectionize different parts of a super, like validation, marshal, unmarshal, etc., and shows comments of each one in the related section. There are also some other minor automated functions that Xua can perform.Entities Documentations
Other than including the comments in the documentation, Xua can automatically generate a table of entity fields, with their types, default values, description, etc. The field description is the comment that comes immediately after the field definition; if no comment is found, the description is set to-. Xua can also sectionize different parts of an entity, and some other automated functions are also present.Entities Graph
Almost any project has some related entities; for example, we may have an entity calledUser that has a field called birthPlace that comes from another Entity called AdministrativeDivision, and an entity called Restaurant that has a field called costumers which comes from User, and a field called city that comes from City. There would be many other entities with relations; these relations can be one-to-one, one-to-many, many-to-many, or many-to-one. Most of these complicated projects have a graph of entities as vertices, showing the relations by edges. Xua is capable of drawing this graph and modify it whenever an entity is modified.Methods Documentations
Other than including the comments in the documentation, Xua can automatically generate a table of the request parameters, and a table of the response parameters, with their types, default values, description, etc. The description of a field is the comment that comes immediately after the parameter definition; if no comment is found, the description is set to-. Xua can also sectionize different parts of a method, and some other automated functions are also present.Book
Book is the name we call a.xua file, or a set of .xua files when the file(s) do(es) not affect the Server project or the Marshal library, just like the one you are reading currently.Foreign Units
Some units are out of our control, they work as they are, but they are our concern since we want to communicate with them.System Resources
System resources are usually procedures and scripts not written in PHP, such as cronjobs, shell commands, Redis queues, foreign language codes, etc. However, we may want to use these resources in our project. This use can be done through a service.For example, assume we have a coding contest website and want to compile and run some tests on uploaded codes. We may have a foreign judge project written in Python that does this for us; we only need to call it. We can write a service called
JudgeService and use it in a method. Or if we want to manage a queue, we can write a service called QueuesService and call it like the following.QueuesService::addToQueue(QueuesService::QUEUE_WAITING_TO_JUDGE_CODES, $uploadedCode)
Libraries
There can be some PHP libraries that we do not wish to rewrite, for example, generating a QR Code, reading an excel file, etc. We can have these codes available and write a service to call these for us. It is essential to mark libraries as resource files inconfig.json, or they will be deleted when cleaning the project.3rd Party Apps
Same as System Resources, and Libraries, we can write services and interfaces to communicate with 3rd Party Apps. For example assume we want to useredis which is a 3rd party tool, we can write a service that does the low-level communications and offers a set of high-level methods to the Xua project.
Introduction
In this chapter, we try to focus on concepts and theories. Reading this chapter helps with understanding the concepts and fundamentals, but turning these theories into practice, needs reading the main chapter of the unit. Only a few units are directly defined by the programmer (namely: Methods, Entities, Supers, Interfaces, Services, Resource Files), and there is a special chapter for each, which you can reach by clicking on them.