| ... | ... | @@ -4,7 +4,59 @@ |
|
|
|
|
|
|
|
|
|
|
|
## Creating a server
|
|
|
|
We shown how to create and start a web service on our [starting site](Home). Sparkling analyzes the methods of the given handler object and uses Spark to add both a GET and a POST request for each, together with parameter and return value conversion. Further, it creates a documentation site for the handler object, listing all service methods available together with a generated Java Interface for Java client instance creation.
|
|
|
|
We shown how to create and start a web service on our [starting site](Home). Sparkling analyzes the methods of the given handler object and uses Spark to add both a GET and a POST request for each method, together with parameter and return value conversion. Further, it creates a documentation site for the handler object, listing all service methods available together with a generated Java Interface for Java client instance creation.
|
|
|
|
|
|
|
|
### [Underlying Spark micro framework](http://sparkjava.com/)
|
|
|
|
Since Sparkling simply connects the Spark server to the handler methods with Spark, you can use __all [Spark functionality](http://sparkjava.com/) furthermore. Nothing special. Add new requests before or after you add a handler with Sparkling, deal with https, etc. Look into the fantastic [Spark documentation](http://sparkjava.com/documentation) for all possibilities. |
|
|
|
You have some possibilities to control server creation with Sparkling:
|
|
|
|
* __Pick the methods__ that should be available via the server:
|
|
|
|
1. `Sparkling.startServer(..)` gives a parameter where you can specify the names of the methods that should not be used.
|
|
|
|
2. Annotate a method with `@Skip4Service`.
|
|
|
|
* Add __several handler objects__ to the server with `Sparkling.addHandler2Server(..)`. You can specify a subpath for each handler object. The only difference to `Sparkling.startServer(..)` it that `Sparkling.startServer(..)` specifies the port of the server also.
|
|
|
|
* Make cleanups at __server shutdown__, when you e.g. have to close some database connections, with `Sparkling.addShutdownRoutine(Runnable runnable)`.
|
|
|
|
* __Suppress documentation__ creation with `createDocumentation=false` as parameter of `Sparkling.addHandler2Server(..)` and `Sparkling.startServer(..)`.
|
|
|
|
* Log __invocation statistics__ with `logInvocationStatsEveryNCalls=N`. The server will log every `N` method invocation the counts which method was called how often since the last server (re)start.
|
|
|
|
|
|
|
|
### Spark as underlying micro framework
|
|
|
|
Since Sparkling simply connects the Spark server to the handler methods with [Spark](http://sparkjava.com/), you can use __all Spark functionality__ furthermore. Nothing special. Add new requests before or after you add a handler with Sparkling, deal with https, and plenty of more. Look into the fantastic [Spark documentation](http://sparkjava.com/documentation) for all possibilities.
|
|
|
|
|
|
|
|
### Data conversion
|
|
|
|
Parameter and return values
|
|
|
|
|
|
|
|
simple vrs json, Polymorph
|
|
|
|
|
|
|
|
### Java method parameter names
|
|
|
|
Sparkling needs to know the parameter names of the handler object methods in order to offer according named parameters for the http GET and POST calls. Since the Java compiler does not provide them per default, we have to take care that Sparkling can get these names at server creation time.
|
|
|
|
|
|
|
|
Since Java version 8 the java compilers offers the command line option `-parameters`. With this flag enabled the compiler will write parameter name metadata into the created bytecode. These names are then available via the reflection API. Take care to enable this flag at compile time of your server.
|
|
|
|
|
|
|
|
__Command line__: `javac -parameters ...`
|
|
|
|
|
|
|
|
__IntelliJ__: Settings => Java Compiler => Additional command line parameters: `-parameters`
|
|
|
|
|
|
|
|
__Maven:__
|
|
|
|
```xml
|
|
|
|
<build>
|
|
|
|
<pluginManagement>
|
|
|
|
<plugins>
|
|
|
|
<plugin>
|
|
|
|
<groupId>org.apache.maven.plugins</groupId>
|
|
|
|
<artifactId>maven-compiler-plugin</artifactId>
|
|
|
|
<version>3.8.1</version>
|
|
|
|
<configuration>
|
|
|
|
<compilerArgs>
|
|
|
|
<arg>-parameters</arg>
|
|
|
|
</compilerArgs>
|
|
|
|
</configuration>
|
|
|
|
</plugin>
|
|
|
|
</plugins>
|
|
|
|
</pluginManagement>
|
|
|
|
</build>
|
|
|
|
```
|
|
|
|
|
|
|
|
In the case you have to work with Java <8 or you don't want or can set the `-parameters` flag for some reason, we offer an annotation `@Named` as alternative. Using this, the parameter name will specified as parameter annotation instead of bytecode metadata. The pro is that you are independent from the compiler flag. The con is that you have to provide the parameter name for each parameter on your own. Use it as follows:
|
|
|
|
|
|
|
|
```java
|
|
|
|
// gives the first parameter the name 'ping'
|
|
|
|
public void myMethod( @Named("ping") String arg0 )
|
|
|
|
```
|
|
|
|
|
|
|
|
Note that if you don't specify anything, Java will name the parameters as `arg0, arg1, ...argN`. The service communication will work with these parameter names also, it looks messy if you have a look on it of course. Nevertheless, if you use the generated java client only, service communication will work as expected. You will only get in contact with the parameter names when you create the http calls on your own. |
