[Minor] code formatting

content/development/_index.md

@@ -131,7 +131,6 @@ You change into the directory of the new project and then build the project by c
 ```shell
 cd <my-artifactId>
 mvn clean package
-
 ```
 
 Start the program using:

content/documentation/components.md

@@ -44,6 +44,8 @@ registered in the `StrolchConfiguration.xml` file with a
 The dependencies is an important feature as the dependencies of a component 
 are always started before the actual component.
 
+## Example Component implementation and configuration
+
 By example of the `MailHandler` we shall show how a strolch component would 
 be implemented.
 
@@ -58,7 +60,7 @@ Then implement a concrete `MailHandler`:
 ```java
 public class SmtpMailHandler extends StrolchComponent implements MailHandler {
 
-  // instance fields with configuration properties to send the mail
+  // TODO instance fields with configuration properties to send the mail
 
   public SmtpMailHandler(ComponentContainer container, String componentName) {
     super(container, componentName);
@@ -67,7 +69,7 @@ public class SmtpMailHandler extends StrolchComponent implements MailHandler {
   @Override
   public void initialize(ComponentConfiguration configuration) throws Exception {
 
-    // store any properties needed from the configuration
+    // TODO store any properties needed from the configuration
 
     super.initialize(configuration);
   }
@@ -75,7 +77,7 @@ public class SmtpMailHandler extends StrolchComponent implements MailHandler {
   @Override
   public void sendMail(String subject, String text, String recipient) {
 
-    // send the e-mail using SMTP, or store in stack to send by thread
+    // TODO send the e-mail using SMTP, or send asynchronously
   }
 }
 ```
@@ -107,7 +109,12 @@ element:
 Now when the agent is started, the component can be retrieved and used. 
 E.g from inside a Service:
 ```java
-MailHandler mailHandler = getComponent(MailHandler.class);
-mailHandler.sendMail("My Subject", "Hello World", "test@test.ch");
+public class MyService extends AbstractService<ServiceArgument, ServiceResult> {
+	@Override
+	protected ServiceResult internalDoService(ServiceArgument arg) throws Exception {
+		MailHandler mailHandler = getComponent(MailHandler.class);
+		mailHandler.sendMail("My Subject", "Hello World", "test@test.ch");
+    }
+}
 ```
 

content/documentation/do-and-donts.md

@@ -10,9 +10,12 @@ The following is a simple list of do's and don'ts:
 * Subclass `ResourceSearch`, `OrderSearch` and `ActivitySearch` when implementing use-case specific search - this allows privilege checking.
 * One Transaction at a time - no TX inside of another TX.
 * Commands are added to TXs and performed on close: `tx.addCommand(Command)` and then `tx.commitOnClose()`
-* Use `tx.flush()` if you need to perform first some work and then as late as possible call `tx.commitOnClose()`
 * Only access `ElementMaps` if really no other way, mostly use `tx.get*By()`, `tx.findBy()` and searches - if a specific get is missing, then add the method to `StrolchTransaction` and send a pull request!
 * Use `tx.stream*()` methods to iterate over all elements, if you don't want to use a search.
 * Don't write logic in REST API beans. Delegate to other services, making your code reusable!
-* Transform to JSON using the `StrolchElementToJsonVisitor`.
+* Marshall to JSON using the `StrolchElementToJsonVisitor`.
+* Unmarshall JSON using `FromFlatJsonVisitor` or if needed `StrolchElementFromJsonVisitor`
 * References between objects is done by adding a `ParameterBag` with the id `relations` to the object and then `StringParameters` with the value being the ID, the UOM set to the type of element being referenced and the Interpretation set to the class type being referenced.
+* Very seldom and sparingly use `tx.flush()` if you need to perform first some work and then as late as possible call `tx.commitOnClose()`
+  
+  The `flush()`-method flushes everything, i.e. rollback isn't possible anymore.