SuperMap iPortal built-in service proxy configuration

The built-in service proxy of SuperMap iPortal refers to the service proxy function that comes with the iPortal product package, which is enabled by default. Besides, iPortal also provides a variety of optional function extension configurations, including: service access statistics , use the HTTPS protocol to enable the service proxy, and the service proxy caching functions. To make the service proxy performance better, it is recommended that you use MySQL/Oracle/PostgreSQL database to store portal data. For database configuration, please refer to: database configuration.

• Service proxy configuration
• Proxied service access statistics configuration
• Enable the service proxy with the HTTPS protocol
• Service proxy caching configuration
  • Ehcache cache configuration
  • Redis cache configuration
• session sharing between iPortal and proxy service
  • Ehcache cache configuration
  • Redis cache configuration

Service proxy configuration

As the iPortal portal administrator, you can set the service proxy related configuration through the sub-node element in the iportal.xml file in the %SuperMap iPortal_HOME%/webapps/iportal/WEB-INF directory. For details, please refer to: iPortal configuration file description.

Example:

   ...

<IportalConfig>

   <serviceProxy>

       <enable>true</enable>

       <enableBuiltinProxy>true</enableBuiltinProxy>

       <port>8195</port>

       <rootUrlPostfix>portalproxy</rootUrlPostfix>

       <httpConnPoolInfo>

            <maxTotal>100</maxTotal>

            <defaultMaxPerRoute>10</defaultMaxPerRoute>

            <connectionTimeout>30000</connectionTimeout>

            <socketTimeout>30000</socketTimeout>

      </httpConnPoolInfo>

   ...

   </serviceProxy>

</IportalConfig>

• <enable>:  Whether to open service proxy. Default is true. To use the built-in service proxy, you also need to set the <enableBuiltinProxy> to true. While to use the independent service proxy, you need to set the <enableBuiltinProxy> to false.
• <enableBuiltinProxy>: Whether to use built-in service proxy or the independent service proxy. Defaults to true, meaning the built-in service proxy is used.
• <port>: The port of the proxy service, defaults to 8195. If the independent service proxy is enabled and no Nginx is used, this parameter needs to be the same with the port of the independent service proxy package. To do this, you need to modify the port of the Tomcat of the independent proxy package, the default value is 8091. If you also use Nginx, the ports can be different. At this point, all you need to do is to configure on Nginx to forward the requests from <port> to the host of the independent proxy.
• <rootUrlPostfix>: The suffix of the proxy service root address. Default value is portalproxy, so the complete address is http://192.168.120.40:8195/portalproxy/iserver/services/map-changchun/rest. You can set as a new suffix, or empty for non-suffix.
• <httpConnPoolInfo>: HttpClient connection pool for the built-in proxy. This setting is used to improve the concurrent performance of the built-in proxy service.
• <maxTotal>: The maximum size of the connection pool of the built-in proxy. Default value is 100. You can set according to the maximum number of concurrent users.
• <defaultMaxPerRoute>: The maximum size of connections for a route address for the built-in proxy. Default value is 10. You can set according to the maximum size of concurrent users that access a single service in portal.
• <connectionTimeout>: The timeout period for establishing a connection with the server when the proxy forwards the request, in ms. The default value is: 30000. You can set it according to the network environment.
• <socketTimeout>: The timeout period for reading data from the server when the proxy forwards the request, in ms. The default value is: 30000. You can set it according to the network environment.

If the iPortal is running in a network environment with dual network adapters or multiple network adapters, to support accessing the proxied services with any ip of the machine, you need to add the <proxyServerRootUrl> node under <service Proxy>. The complete configuration is as follows:

<IportalConfig>

   ...

   <serviceProxy>

       <enable>true</enable>

       <enableBuiltinProxy>true</enableBuiltinProxy>

       <port>8195</port>

       <rootUrlPostfix>portalproxy</rootUrlPostfix>

       <proxyServerRootUrl>http://{ProxyHost}[:port]</proxyServerRootUrl>

       <httpConnPoolInfo>

            <maxTotal>100</maxTotal>

            <defaultMaxPerRoute>10</defaultMaxPerRoute>

            <connectionTimeout>30000</connectionTimeout>

            <socketTimeout>30000</socketTimeout>

      </httpConnPoolInfo>

   ...

   </serviceProxy>

</IportalConfig>

In the above configuration, {ProxyHost} is a placeholder, which will dynamically display the IP address; [:port] is a variable to represent the port, representing the listening port of the proxy service. For example: <proxyServerRootUrl>http://{ProxyHost}:8195</proxyServerRootUrl>

Note:

• iPortal portal homepage address: http://<server>:<port>/iportal (server depends on the IP of the server where iPortal is deployed, port depends on the port number configured in %SuperMap iPortal_HOME%\conf\server.xml) and the above The proxy configuration item is irrelevant.
• "Other service types" in the supported service types for registering doesn't support proxy service, which means if proxy service is enabled, the registered other type of services can't be proxied, or registering an other type service will fail.
• If you disable the built-in/independent proxy, you need to restart iPortal service to make the configuration effect.

Proxied service access statistics configuration

To open the proxied service access statistics, you need to set <enableAccessStatistics> to true in iportal.xml like the following:

<IportalConfig>

   ...

   <serviceProxy>

       <enable>true</enable>

       <enableBuiltinProxy>true</enableBuiltinProxy>

       ...

      <!-- Proxy access statistics feature settings. Enabled by default -->

      <enableAccessStatistics>true</enableAccessStatistics>

   </serviceProxy>

</IportalConfig>

• <enableAccessStatistics>: Whether to enable the service access statistics function. Default value: true.

Enable the service proxy with the HTTPS protocol

The service proxy defaults to use http protocol, which means no matter the original registered service uses http or https, the proxied address uses http protocol. To configure supporting https, find the following section in <serviceProxy> element in iportal.xml:

<serviceProxy>

      ...

        <!-- Set which protocol to be used to enable proxy service. Http protocol will be used by default. If set to https, you need to set httpsSetting-->

        <!-- <scheme>http</scheme>

                   <httpsSetting>

                         <keyStorePath>D:\key.keystore</keyStorePath>

                         <keyStorePassword>123456</keyStorePassword>

                   </httpsSetting>  -->

    ...

</serviceProxy>

Comment out the above configuration, make the following changes(bold part):：

<serviceProxy>

      ...

        <!-- Set which protocol to be used to enable proxy service. Http protocol will be used by default. If set to https, you need to set httpsSetting-->

        <scheme>https</scheme>

                 <httpsSetting>

                        <keyStorePath>D:\key.keystore</keyStorePath>

                        <keyStorePassword>123456</keyStorePassword>

                 </httpsSetting>

    ...

</serviceProxy>

• <scheme>: Decide to use which protocol to start the service proxy. The default value is http. To use https protocol, set it to https.
• <keyStorePath>: The location of the certificate. iPortal uses this certificate to start the service proxy with https protocol. For generating certificate, see: Geneterating server certificate (public key).
• <keyStorePassword>: Password of the certificate, ie., the password of key.keystore.

Note:

• If your iPortal is configured to start with the HTTPS protocol, you must set the service proxy to start with the HTTPS protocol, so that the proxy service address can be accessed normally.

Service proxy caching configuration

The proxy caching is used to accelerate the access speed of proxied GIS services. The theory is to store the frequently used results of permission verifications and the mapping of original service and proxied service queried from database to cache.

Built-in proxy supports two cache types, Ehcache and Redis. Ehcache is used by default, you can use it directly.

Ehcache cache configuration

Ehcache configuration is shown as follows:

<serviceProxy>

    ...

    <cacheConfig>

        <enable>true</enable>

        <type>EHCACHE</type>

        <cacheServerConfig>

            <ehcacheConfigPath>./WEB-INF/iportal-ehcache.xml</ehcacheConfigPath>

            ...

        </cacheServerConfig>

    </cacheConfig>

</serviceProxy>

• <enable>: Used to set whether to enable the service proxy cache. The default value is true.
• <type>: Used to set the cache type, the characters need to be capitalized. The default value: EHCACHE. To use Redis cache, set it to REDIS.
• <cacheServerConfig>: Used to configure the cache server.
• <ehcacheConfigPath>: Used to set  the path of the Ehcache configuration file, which defaults to the iportal-ehache.xml configuration file of the built-in Ehcache of iPortal, i.e., under the [SuperMap iPortal installation directory]\webapps\iportal\WEB-INF direcotry. And you can also write your own independent cache configuration file.

Redis cache configuration

Before configuring Redis cache, make sure you've installed Redis. To download and install Linux-version Redis, go to: https://redis.io/download.

This section takes Windows-version Redis as the example to show the configurations. Redis doesn't have an official Windows version. The Microsoft Open Tech group develops and matains a Win64 version, the download address is https://github.com/MicrosoftArchive/redis/releases.

After obtained the Redis, click redis_server.exe inside the folder to start Redis service. To ensure the proxy service's availability, the Redis service should always be available.

After installing and start Redis service, find <cacheConfig> element in iportal.xml.  Set the value of <type> under <cacheConfig> as REDIS, and remove the Ehcache config shown below in <cacheServerConfig> node.

<cacheName>iportalProxyCache</cacheName>

<ehcacheConfigPath>./WEB-INF/iportal-ehcache.xml</ehcacheConfigPath>

Comment out the Redis cache configuration shown as follows:

<serviceProxy>

    ...

    <cacheConfig>

        <enable>true</enable>

        <type>REDIS</type>

        <cacheServerConfig>

            <server>

               <nodes>192.168.112.231:7001</nodes>

               <timeout>3000</timeout>

               <password></password>

            </server>

            <jedisPoolConfig>

               <maxTotal>2048</maxTotal>

               <maxIdle>128</maxIdle>

               <maxWaitMillis>-1</maxWaitMillis>

               <testOnBorrow>true</testOnBorrow>

            </jedisPoolConfig>

        </cacheServerConfig>

    </cacheConfig>

</serviceProxy>

• <enable>: Used to set whether to enable the service proxy cache. The default value is true.
• <type>: Used to set the cache type, the characters need to be capitalized. The default value: EHCACHE. To use Redis cache, you can set to REDIS.
• <cacheServerConfig>: Used to set configure cache server.
• <nodes>: Used to set the Redis server node. If Redis uses cluster, you can configure multiple " host:port" which need to be separated by "|".
• <timeout>: Used to set Redis service connection timeout, in ms.
• <password>: Used to set the access password for the Redis service.
• <maxTotal>: Used to set the maximum number of the connections for Redis instances.
• <maxIdle>: Used to set the maximum number of idle Jedis instances of a Pool.
• <maxWaitMillis>: Used to set the maximum time to wait for available connection in ms, default: -1, meaning never expires.
• <testOnBorrow>: Used to determine wether to perform validate operation in advance when borrowing a Jedis instance, default is true, indicating that the borrowed Jedis instance is available. This parameter is not recommended for modification.

session sharing between iPortal and proxy service

It's essential to configure session sharing before proxy works successfully. Specifically, you need to configure to store the Cookie information of logged in users.

The built-in proxy supports two ways to store the Cookie of logged in uses: Ehcache and Redis cache. Ehcache is used by default, you can use it directly.

Ehcache cache configuration

Ehcache configuration is shown as follows:

<IportalConfig>

    ...

    <cookieStorage>

        <type>EHCACHE</type>

        <cacheServerConfig>

            <ehcacheConfigPath>./WEB-INF/iportal-ehcache.xml</ehcacheConfigPath>

            ...

        </cacheServerConfig>

    </cookieStorage>

</IportalConfig>

• <type>>: Used to set the cache type, the characters need to be capitalized. The default value: EHCACHE. To use Redis cache, you can set to REDIS.
• <cacheServerConfig>: Used to set configure cache server.
• <ehcacheConfigPath>: Used to set  the path of the Ehcache configuration file, which defaults to the iportal-ehache.xml configuration file of the Ehcache built into the iPortal system under the [SuperMap iPortal installation directory]\webapps\iportal\WEB-INFdirecotry. And you can also write your own independent cache configuration file.

Redis cache configuration

If you've installed Redis service in previous step: Proxy service cache configuration, you only need to finish the following configurations.

Find <cookieStorage> sub-node in iportal.xml, set to use Redis cache, and remove the Ehcache config shown below in <cacheServerConfig> node.

<cacheName>iportalProxyCache</cacheName>

<ehcacheConfigPath>./WEB-INF/iportal-ehcache.xml</ehcacheConfigPath>

Comment out the Redis cache configuration shown as follows:

<IportalConfig>

    ...

    <cookieStorage>

        <type>REDIS</type>

        <cacheServerConfig>

            <server>

               <nodes>127.0.0.1:6379</nodes>

               <timeout>3000</timeout>

               <password></password>

            </server>

            <jedisPoolConfig>

               <maxTotal>512</maxTotal>

               <maxIdle>32</maxIdle>

               <maxWaitMillis>-1</maxWaitMillis>

               <testOnBorrow>true</testOnBorrow>

            </jedisPoolConfig>

         </cacheServerConfig>

      </cookieStorage>

    ...

</IportalConfig>

• <type>: Used to set the cache type, the characters need to be capitalized. The default value: EHCACHE. To use Redis cache, you can set to REDIS.
• <cacheServerConfig>: Used to set configure cache server.
• <nodes>: Used to set the Redis server node. If Redis uses cluster, you can configure multiple " host:port" which need to be separated by "|".
• <timeout>: Used to set Redis service connection timeout, in ms.
• <password>: Used to set the access password for the Redis service.
• <maxTotal>: Used to set the maximum number of the connections for Redis instances.
• <maxIdle>: Used to set the maximum number of idle Jedis instances of a Pool.
• <maxWaitMillis>: Used to set the maximum time to wait for available connection in ms, default: -1, meaning never expires.
• <testOnBorrow>: Used to determine wether to perform validate operation in advance when borrowing a Jedis instance, default is true, indicating that the borrowed Jedis instance is available. This parameter is not recommended for modification.