.. _proxy-label:

=======
 Proxy
=======

Be sure to have read this topic before moving on : :ref:`concepts-proxy-label`.

There are currently 3 different kinds of proxy in GeoPrisma :

.. _proxy-serviceproxy-label:

ServiceProxy
-------------

The most used kind of proxy in GeoPrisma.  There is one ServiceProxy for each
existing :ref:`concepts-service-label`.

Here's the mandatory parameters to have when querying for a "Service" type query :
 * osmservice (name of the service to use)
 * osmresource (name of the resource to query)


.. _proxy-widgetproxy-label:

WidgetProxy
------------

This kind of proxy is used to access custom methods defined inside a
:ref:`concepts-widget-label`, more precisely in the *.php* file in the widget's
directory (in client directory).  It is mainly used to accomplish tasks that
no service could do.

There are two ways to access a WidgetProxy :

1) By specifying a **blank service** :

   When using this method, first you need to specify a 'blank' service in the
   query parameters :

   .. code-block:: xml

      &osmservice=__blank__

   Then, you need to have these mandatory parameters set :
    * osmwidgettype (type of widget that has the process, in lowercase)
    * osmprocess (the name of the process (php method name) to call.  This name
      must be in the list of supported process of the widget in order to be
      accessed.  See the 'getProcessList' method inside the *.php* file of
      the widget.)


2) By using **Service of 'widget' type** (*legacy method*) :

   First, in the config, there must be a Service of 'widget' type defined :

     .. code-block:: xml

        <services>
          <widget>
            <name>WidgetService</name>
          </widget>
        </services>

   Then, in the config again, there must be a DataStore linked to this service
   that tells the widgettype and the process (method) to use :

     .. code-block:: xml

        <datastore>
          <name>DataStoreWidget</name>
          <service>WidgetService</service>
          <params>
            <widgettype>wmslayeradder</widgettype>
            <method>methodManager</method>
          </params>
        </datastore>

   Finally, a Resource linked to the widget of the right type must have the
   DataStore defined :

     .. code-block:: xml
    
        <resource>
          <name>R_MyResource</name>
          <datastores>
            <datastore>DataStoreWidget</datastore>
          </datastores>
          <widgets>
            <widget>MyWMSLayerAdderWidget</widget>
          </widgets>
        </resource>

   To access the proxy, you must define the name of the Service and Resource defined above by using the same parameters (as if it was a ServiceProxy) :     
    * osmservice (name of the widget type service to use)
    * osmresource (name of the resource to that is linked to the widget
      datastore)

   .. note:: This method is only supported by the 
             :ref:`xmlconfig-driver-label` and
             :ref:`xmlworkspaceconfig-driver-label` config drivers

   .. note:: Since all the config objects required for this method can be
             considered as 'dummy' (they are no 'real' Service, DataStore and
             Resource objects), the other (first) method was implemented.

Here's some widgets that use the WidgetProxy :
 * :ref:`widget-merge-label` (legacy)
 * :ref:`widget-split-label` (legacy)
 * :ref:`widget-wmslayeradder-label`


.. _proxy-configproxy-label:

ConfigProxy
------------

Pretty much similar to the WidgetProxy, this one is used to access methods
defined inside the :ref:`concepts-config-label` currently being used.  The
results are always returned in JSON.

The way to access it is also similar to the WidgetProxy first method.  You need
to specify a 'blank' service in the  query parameters :

.. code-block:: xml

   &osmservice=__blank__

Then, you need to have this mandatory parameter set :
 * osmprocess (the name of the process (php method name) to call.  This name
   must be in the list of supported process of the config in order to be
   accessed.  See the 'getProcessList' method inside the config file).

Here's some example of queries and responses using the ConfigProxy :


Query (right) :

.. code-block:: php

   proxy.php?osmservice=__blank__&osmprocess=getAuthorizedResources

Response (ok) :

.. code-block:: php

   {"result":{"total":6,"authorized":["3","7","6","4","2","5"]}}

Query (wrong) :

.. code-block:: php

   proxy.php?osmservice=__blank__&osmprocess=dummy

Response (error) :

.. code-block:: php

  {"error":"osmprocess param has an invalid value. Possible values are : getAuthorizedResources"}