GroIMP wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== HTTP server ======

It is possible to start GroIMP as a HTTP server to then send model paths via HTTP for GroIMP to execute. After GroIMP executed the model, values can be returned to the HTTP client who send the request. It is possible to send several models in series or in parallel. 


<uml>@startuml
hide footbox
title HTTP server

User -> GroIMP: Start GroIMP
User -> GroIMP: Send Model-path
GroIMP -> User: Return result
User -> GroIMP: Close GroIMP

@enduml</uml>
===== Execution =====


The HTTP server is part of every GroIMP release and can be executed as an command through the GUI or as a headless command.

==== GUI ====

{{:user-guide:additional_interfaces:open_http_server.png?direct&200 |}} In the main GroIMP menu under the section Net, the entry Open HTTP Server can be found. This will lead to a popup requesting the port number of the server (for more information about the port see below). After a port was given (usually the default one is fine) a new workbench with only the Messages panel is opened. The server now runs until this workbench is closed.


==== Headless ====

The GroIMP [[01_user_documentation:10_additional_interfaces:headless|headless interface]] allows the execution of specific commands without starting the GUI by using the -cmd command. 

In the case of the http server this command is as following:

<code>
java -jar core.jar --headless -- -cmd "/http/server=58080"
</code>
The name core.jar can variate debending on the way GroIMP was installed. 
"58080" is in this case the port, which can be changed if needed.
  

===== Commands =====

To interact with a running HTTP server currently only two commands are available. 
The URL schema is: 
  http://<serverIP>:<port>/<command>?<value> 

In most cases the start will be:
  http://localhost:58080/<command>?<value>

==== About ====

  http://localhost:58080/about

This command returns the current version of the installed plugins and the list of the available HTTP commands.

==== Open ====

  http://localhost:58080/open?<path/to/your/model.gsz>

This command will open the model provided as a value and execute the startup function. After the execution is done the request is returned and if configured the response value is given to the client. 
**It is important to notice that the path is interpreted starting at the root directory given in the options.**



===== RGG interaction =====

As any other GroIMP interface, the HTTP server executes the startup function when a project is opened. 
This function can be overwritten/extended to start a simulation defined in the run function, using the runLater function. 

==== HttpResponse ====

If a model was executed with the HTTP server, it can access the http response, to read additional information or to return data to the client.
The HttpResonse object can be accessed by using the workbench of the project using the static get function:
<code java>
HttpResponse resp = HttpResponse.get(workbench());
</code>

Using the HttpResponse open access to several functions, a full list can be found [[https://javadoc.grogra.de/imp/de/grogra/imp/net/HttpResponse.html|here]]. The most important once are listed below:

=== setContent ===

The setContent function defines what is responded to the client after the send command is executed.
To proper define this the mimeType (what kind of data is it) and the content must be provided. The content can be provided as a byte array or as encoded text using two strings, one for text and one for the encoding (most likely UTF-8).


=== Send ===

Executing the send command sends the HttpResponse to the client. A boolean parameter defines if possible content should be returned.

If needed it is also possible to add a HTTP response code to and a reason for the code as parameters, to have a more clear communication with the client. 


=== sendBadRequest ===

This is mainly a wrapper for the send command to notify the client that something went wrong and the request cant be handled.


=== getRequest ===

This function gives the project access to the request of the user (the specification of the class can be found [[https://javadoc.grogra.de/utilities/de/grogra/http/Request.html | here]]).

Using this request object, it is possible to access the original query with getQuery() which 
provides the last section of the URL or the getContent() function which returns the body of the request as a byte array that then can be handled as needed.

  

==== Multi-use Model ====

Using the HttpResponse.get function will return null if the model was not opened with a http server. Therefore this can be used to ensure that the predefined simulation is not starting automatically if the model was opened with the GUI for modelling.

===== Options =====

There are two options for the HTTP server that can be configured using the [[01_user_documentation:user-guide:panel_options|preferences]] under HTTP Server.

==== Root directory ====

In the subsection Open Project the root directory can be defined. This option defines where the server starts looking up the path given in the open command. By default this should be the home directory of the user.

==== Port ====

In the subsection Open HTTP server the default port which is suggested by the gui dialog can be defined. This might be useful for a setup where the original default port is often occupied.
  
===== Tutorials =====

  * [[02_user_tutorials:07_additional_interfaces:http_server:getting_started|Start a http model]]



===== *Server-Port =====

A port on a computer is used to define which application is actually meant by a network request.
This is very useful to run several applications are using network protocols at the same time. 
For this to work the port needs to be unique, meaning no two applications can "listen" to the same port at the same time. 
Therefore in GroIMP it is possible to define which port is suppose to be used, for the case that an other application is already using the default one. Or for the scenario of running two GroIMP http server at the same time.