IUP ISI/MediaWiki-Silk/Architecture

Introduction

API

The API is composed of some classes (UserGroup, Namespace, General, Page...) and a MediaWiki class to access data.

Library architecture at the begining

The library is composed of a unique class: MediaWiki.

Choice architecture

Synchronous or asynchronous?

Two choices are possible to develop the request management in the library: synchronous and asynchronous.

Synchronous way will lead us to use normal function call. But, since we expects the end of the function, the interface can freeze especially if there is a lot of latency. Moreover, this way will allow to not use signals.

Asynchronous way don’t block the interface because the application doesn’t wait the result of each request to execute the program. This method will lead us to use signals to access to the result.

On the one hand, use synchronous way will lead to use a QEventloop to avoid the freezing and a QNetworkAccessManager in synchronous mode. Otherwise, this way can involve the use of different threads in the application.

On the other hand, use asynchronous way will lead us to use signals and a QNetworkAccessManager in asynchronous mode.

To conclude, we choose the asynchronous one. Moreover, this method is the one used in the library architecture at the begining. But the asynchronous way give the problem of access to the result.

Get the request’s result

We can use three methods to get the result. First, we can develop accessors. This way can cause risks of a call before the signal. This method use a synchronous call. A solution can be to specify this trouble in the documentation of the API.

The second method consists in using a signal having the result as parameter. This way respect the asynchronous semantic but the result is pass by value. For example, we can see it when we copy a list. The pass by value will be a trouble because it is something heavy in the previous example. A solution could be using pass by pointer or smart pointer.

The last method consists in using a signal, like the previous way, which the result as parameter. This method respect the asynchronous semantic but the result is pass by reference. The problem is taht the visibility of errors by the slots is lesser.

Develop Unique class vs multiple classes?

Unique class

• Advantage
  • No memory managing
  • The request calls are normal : wiki->allpagesRequest()
• Disadvantage
  • Readability
  • Can handle only 1 request at a time.

Multiple classes

• Advantage
  • Readability
  • Can handle some requests at a time.
• Disadvantage
  • The memory management

Technical contacts requirements

First, the technical contacts want a asynchronous interface: ”Even if you use a QEventLoop,you'll often need different threads in the application, and those can be a bitch. You can have a look at the current MediaWiki class to how those signals / slots should look like.”

Secondly, to call a request, the code should look like:

  MediaWiki * mw = new MediaWiki(“mon_url”);
  mw->allpagesRequest();
  connect(mw, SIGNAL(allpagesResult(QList<MediaWiki::Page>)),
              SLOT(allpagesProcess(QList<MediaWiki::Page>));

MediaWiki UML

MediaWiki

The MediaWiki class allows developers to call asynchronous request to access the MediaWiki data. For this, developers call a request like allpagesRequest() who send the request with the QNetworkAccessManager. To process the result, developers connect the signal allpagesResult() with his own slot. Because the class MediaWiki needs to emit signals, MediaWiki inherit QObject.

Why don’t separate the code

To follow the first development of the MediaWiki class and with the agreement of the technical contacts, we don’t separate MediaWiki and its requests.

Who manages the memory?

There is one class, so the library can manage the memory.

Why QNetworkAccessManager?

It’s the Qt class for HTTP requests and it is asynchronous. By the way, we can use this class in a synchronous way using QEventLoop.

KDE library?

At this time, we don’t use KDE library because Qt provides the necessary.

Namespace

To avoid name conflicts with others libraries, we propose to define a namespace like silk::. mediawiki:: was a possibility but there will be a redundancy (mediawiki::MediaWiki).

Binary compatibility

For ensure the binary compatibility, we’ll use only a pointer to MediaWikiPrivate, which will contain attributes. In this case, modify the attributes doesn’t fail a class which uses MediaWiki.