Limax Project

7.3 Application Configuration

A Limax operating environment is supported by an Auany server. The services of multiple applications could be run in one operating environment. Each application could run multiple parallel services. One service could consist of multiple Providers. For a particular application, the Provider is allowed to publish the public information provided to the client to use.

Provider publish the information

The Provider framework periodically requests the JSON object from the application Provider. This object is eventually released through the http service of the Auany.
- Implementation
```
public interface JSONPublisher {
    JSONSerializable getJSON();
    long getDelay();
}
```
  When the Provider implements the ProviderListene, the JSONPublisher interface is also implemented at the same time. Including:
  
  getJSON：return a JSON object
  
  getDelay：the delay that the system obtains the JSON object next time, milliseconds is the unit.
- Configuration
  
  There is no extra configuration for the Provider. There is jsonPublishDelayMin attribute (introduce later) in the configuration of the Auany application, and this attribute constrains the minimum of the delay, which means that the max(jsonPublishDelayMin, JSONPublisher.getDelay()) determins the actual delay. This configuration attribute could avoid the error that the wrong implementation of the JSONPublisher causes the Provider to attack the Auany.

Endpoint application information acquision

The Endpoint requests the application configuration information from the http server provided by the Auany, interpretting as the description of the relative language. The implementation is accessing the http://auanyserver/app?{servicetype}=appid[&additionalQuery] and obtaining a JSON object for analysis, among which the servicetype : { native, ws, wss } is servicetype=native for non WebSocket application. The additionalQuery is the query parameter promised by HTTP proxy server to filter the result set returned by auany.
- Implementation
```
List<ServiceInfo> Endpoint.loadServiceInfos(String httpHost, int httpPort, int appid, long timeout, int maxsize, File cacheDir, boolean staleEnable);
List<ServiceInfo> Endpoint.loadServiceInfos(String httpHost, int httpPort, int appid, String additionalQuery, long timeout, int maxsize, File cacheDir, boolean staleEnable);
```
  Including:
  
  httpHost，httpPort：the Auany http server address
  
  appid：the id allocated by the operating framework
  
  additonalQuery: the query parameter promised by http proxy server.
  
  timeout, maxsize, cachedir, staleEnable：the request parameters of the http service. The timeout determins the request timeout, the maxsize constrains the maximum size of the returned information, the cacheDir provides the local cache directory, and the staleEnable determins whether the old data in the local cache will be used when the request fails.
  
  The multiple parallel services could be run in the same application and returns List. The ServiceInfo among the List provides five methods:
  
  1. int[] getPvids();
  
  obtains the pvid referenced by this service, and the order is detemined by the Auany configuration.
  
  2. int[] getPayids();
  
  obtains the payment id of this service, usually one service has only one id.
  
  3. JSON[] getUserJSONs()
  
  The JSON object here is provided by the JSONPublisher mentioned before. Because one service could be provided by multiple Provider, and whether the Provider supports the JSON announcement is optional, the JSON array is returned here and the array size is not consistent with the size returned by the getPvids().
  
  4. boolean isRunning()
  
  Whether this service is running.
  
  5. String getOptional()
  
  This method is related to the operating environment, and returns the special information set by the operating environment for the service, such as maintaining information.

Auany configuration

The appconfig.xml provides the application configuration of the Auany. This configure file could add the new information via merge during the system operating and does not need to shutdown to maintain.
- The relative configuration of the Switcher
```
<switcher host="127.0.0.1" id="1" key="abc" port="10000" type="native"/>
<switcher host="127.0.0.1" id="2" key="abc" port="10001" type="ws"/>
```
  The internal Switcher of the Auany corresponds to the configure file of the Switcher service, including:
  
  type：the Switcher type, includes the native, ws and wss. The native corresponds to the Limax network service, the ws and the wss correspond to the WebSockect service, among which the wss supports the ssl.
  
  id：the SwitcherId, the unique one allocated in the entire operating environment.
  
  key：corresponds to the key in the configuration of the Switcher server, and is used to authenticate the Switcher server.
  
  host，port：the external service address of the Switcher server
  
  Compare to the Switcher item in the Switcher server configure file service-switcher.xml:
```
<Switcher key="abc" …… >
    ……………………………..
    <native id="1"/>
    <ws id="2"/>
</Switcher>   
```
  When the Switcher launches, it sends the announcement to the Auany by constructing the { key, native-id[], ws-id[], wss-id[] } information. If the information could not match the configure information in the Auany, the Auany will order the Switcher to exit and report the error reason in the Switcher log.
  
  Attention:
  
  1. The different Switcher server should configure different key, and avoid that the id configure error causes the conflict.
  
  2. It might be multiple Switcher services with the same time, corresponding to bind different network interface or port.
  
  3. Whether the Switcher configuration should have some type depends on the Manager configuration of the access service.
  
  4. The host of the Auany configuration could not correspond to the localIp attribute of the access service Manager in the Switcher configuration. Because it can not make sure whether the NAT exists in front of the Switcher, the host here must use the actual external IP.
- The relative configure of the shared Provider
```
<provider id="1" jsonPublishDelayMin="0" key=""/>
<provider id="12" jsonPublishDelayMin="0" key=""/>
```
  id：ProviderId, the internal global unique in the operating environment.
  
  key：the key of the Provider, is used to verify the legitimacy of the Provider service, corresponding to the key of the Provider configuration.
  
  jsonPublishDelayMin：the minimum time interval between the two JSON object requst of this Provider, 0 means that this Provider is forbiddedn to publish the JSON information.
  
  The shared Provider is referrenced by the app item of the application configuration, or the service item below.
  
  The Provider not referenced by any app or service is optional shared Provider. The client could request this Provider for service or not when login. Among them, the provider id=1 is reserverd by Auany to provide the AuanyService.
- Application configuration
```
<app id="1" jsonPublishDelayMin="15000" maxSubordinates="0" providerMatchBidirectionally="true" shareProvider="">
    <service id="1" shareProvider="" switcher="1,2,3">
        <provider id="100" key=""/>
    </service>
</app>
<app id="2" jsonPublishDelayMin="5000" maxSubordinates="8" providerMatchBidirectionally="true" shareProvider="12">
    <service id="1" shareProvider="" switcher="1,2,3">
        <provider id="200" key=""/>
    </service>
    <service id="2" shareProvider="" switcher="1,2,3">
        <provider id="300" key=""/>
    </service>
</app>
```
  app element：
```
<app id="1" jsonPublishDelayMin="15000" maxSubordinates="0" providerMatchBidirectionally="true" shareProvider="">
```
  id：the application id, internal globally unique in the operating environment
  
  jsonPublishDelayMin：the publish time interval of the JSON objects of all private Provider except the public Provider used this application
  
  maxSubordinates：the maximum sub account quantity supported by this application, 0 means the sub account is forbidden.
  
  providerMatchBidirectionally:providers match bidirectionally, if true, providers requested match providers configured bidiectionally. if false, request non-empty subset of providers configured is permitted.
  
  shareProvider：the shared Provider list seperated by the comma. Referring to the id(=1) of the Auany service is forbidden.
  
  service element:
```
<service id="1" shareProvider="" switcher="1,2,3">
```
  id：service id, the unique is guaranteed in an application service configuration.
  
  shareProvider：the shared ProviderId seperated by the comma. Referring to the id(=1) of the Auany service is forbidden.
  
  switcher：the SwitcherId list seperated by the comma.
  
  private Provider element:
```
<provider id="200" key=""/>
```
  compare to the shared Provider element, no jsonPublishDelayMin attribute here. This attribute inherits from the app element.
  
  Attention:
  
  1. The shared Provider and private Provider allocate the id in the same allocation domain, which means that it does not allow the id conflict between the shared Provider and private Provider.
  
  2. When the client initates the application information request from the server, the most important information is the Switcher address of the next connection. The Auany only announces the launched Switcher. If it configured in the configure file, but the actual Switcher service does not launch, the corresponding configure address does not be announced. If all the Switcher services corresponding to the service type do not launch, the announced service running status is false.
  
  3. The pvid announcement order of the service information is determined by the private Provider list, shared Provider list referenced by the service, and the shared Provider list referenced by the app.
  
  4. If the Provider referenced by a service does not totally launch, the announced service running status is false.
- Add new service configuration
  
  In the Auany configure file, two attributes of the Auany element.
  
  appConfigPatch：the patch file name, the default name is appnew.xml
  
  appConfigPatchCheckPeriod：the patch file detect period, the defalt value is 30000 which means 30 seconds.
  
  the detailed operation：
  
  1. New a configure file appnew.xml with the same format as the appconfig.xml. In this file, the new Switcher, new shared Provider, new app, and the new service of the existed app could be created, only if there is no id conflict.
  
  2. Copy the appnew.xml to the same directory of the appconfig.xml. No later than 30 seconds, the appnew.xml is renamed as the appnew.xml.result, and the merge result information is appended to the end of the file.
  
  3. If success, the new configuration is loaded into the Auany service, the appnew.xml is merged to the appconfig.xml, and the previous appconfig.xml is backup as the appconfig.xml.bak.
  
  4. If fail, the appended merge result information indicates the error reason, such as the operation exception, or id conflict. The service running in this condition is not affected and the appconfig.xml has no change.
- Update the service's Optional information
```
public interface AppManagerMXBean {
    void setServiceOptional(int appid, int serviceid, String optional);
}
```
  Through accessing the JMX service of the Auany, with the appid and serviceid as the key, and the optional as the value, calls the setServiceOptional method. Then, the optional information can be obtained by ServiceInfo.getOptional() from the relative Endpoint.
- Matters need attention
  
  1. The application should provide the information such as the service name via its own JSON announcement, and does not overly depend on the service information of the Auany announcement. A typical implementation is creating a map, obtaining the application service information of the JSON announcement as the key to index the ServiceInfo returned by the announcement.
  
  2. The all kinds of request interface provided by the Endpoint related to the Switcher ip and Switcher port provides the relative ServiceInfo version. Before using ServiceInfo, it should determine whether the service is running to avoid generating the running error.
  
  3. In the operating environment, in order to reduce the Auany http service load, the http proxy server could be deployed to accelerate.

Prev Next

7.3 Application Configuration

Provider publish the information

Endpoint application information acquision

Auany configuration