Backend: exception handlers, controller advice, interceptors and validation

docs/demos/backend/src/main/java/com/codenameone/developerguide/backend/advice/Address.java

@@ -0,0 +1,30 @@
+/*
+ * Copyright (c) 2012, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+package com.codenameone.developerguide.backend.advice;
+
+import com.codename1.backend.validation.NotBlank;
+
+/** A nested object the validation example descends into. */
+public class Address {
+    @NotBlank public String city;
+}

docs/demos/backend/src/main/java/com/codenameone/developerguide/backend/advice/ApiErrors.java

@@ -0,0 +1,37 @@
+/*
+ * Copyright (c) 2012, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+package com.codenameone.developerguide.backend.advice;
+
+import com.codename1.backend.HttpServer;
+import com.codename1.backend.annotations.ExceptionHandler;
+import com.codename1.backend.annotations.RestControllerAdvice;
+
+// tag::backend-web-controller-advice[]
+@RestControllerAdvice
+public class ApiErrors {
+    @ExceptionHandler(IllegalArgumentException.class)
+    public HttpServer.Response badInput(IllegalArgumentException e, HttpServer.Request request) {
+        return HttpServer.Response.text(400, e.getMessage()).header("X-Error", "input");
+    }
+}
+// end::backend-web-controller-advice[]

docs/demos/backend/src/main/java/com/codenameone/developerguide/backend/advice/Audit.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2012, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+package com.codenameone.developerguide.backend.advice;
+
+import com.codename1.backend.HttpServer;
+import com.codename1.backend.annotations.Component;
+import com.codename1.backend.annotations.Order;
+import com.codename1.backend.web.HandlerInterceptor;
+import com.codename1.backend.web.HandlerMethod;
+
+// tag::backend-web-interceptor[]
+@Component
+@Order(1)
+public class Audit implements HandlerInterceptor {
+    private final AuditTrail audit = new AuditTrail();
+
+    public HttpServer.Response preHandle(HttpServer.Request request, HandlerMethod handler) {
+        return null;                       // null proceeds; a Response answers instead
+    }
+
+    public void afterCompletion(HttpServer.Request request, HandlerMethod handler,
+                                HttpServer.Response response, Throwable failure) {
+        audit.record(handler.getPattern(), failure == null ? "ok" : failure.toString());
+    }
+}
+// end::backend-web-interceptor[]

docs/demos/backend/src/main/java/com/codenameone/developerguide/backend/advice/AuditTrail.java

@@ -0,0 +1,35 @@
+/*
+ * Copyright (c) 2012, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+package com.codenameone.developerguide.backend.advice;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/** Where the interceptor example records what happened. */
+public class AuditTrail {
+    private final List<String> entries = new ArrayList<String>();
+
+    public synchronized void record(String route, String outcome) {
+        entries.add(route + " " + outcome);
+    }
+}

docs/demos/backend/src/main/java/com/codenameone/developerguide/backend/advice/NewNote.java

@@ -0,0 +1,39 @@
+/*
+ * Copyright (c) 2012, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+package com.codenameone.developerguide.backend.advice;
+
+import com.codename1.backend.validation.Max;
+import com.codename1.backend.validation.Min;
+import com.codename1.backend.validation.NotBlank;
+import com.codename1.backend.validation.Size;
+import com.codename1.backend.validation.Valid;
+import java.util.List;
+
+// tag::backend-web-validation-model[]
+public class NewNote {
+    @NotBlank @Size(max = 200) public String title;
+    @Min(1) @Max(5) public int priority;
+    @Valid public Address address;
+    @Valid public List<Tag> tags;
+}
+// end::backend-web-validation-model[]

docs/demos/backend/src/main/java/com/codenameone/developerguide/backend/advice/NoteMissing.java

@@ -0,0 +1,30 @@
+/*
+ * Copyright (c) 2012, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+package com.codenameone.developerguide.backend.advice;
+
+/** Thrown when a note does not exist. */
+public class NoteMissing extends RuntimeException {
+    public NoteMissing(long id) {
+        super("No note " + id);
+    }
+}

docs/demos/backend/src/main/java/com/codenameone/developerguide/backend/advice/NoteView.java

@@ -0,0 +1,29 @@
+/*
+ * Copyright (c) 2012, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+package com.codenameone.developerguide.backend.advice;
+
+/** A note as the advice examples return it. */
+public class NoteView {
+    public long id;
+    public String title;
+}

docs/demos/backend/src/main/java/com/codenameone/developerguide/backend/advice/NotesWithHandler.java

@@ -0,0 +1,54 @@
+/*
+ * Copyright (c) 2012, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+package com.codenameone.developerguide.backend.advice;
+
+import com.codename1.backend.annotations.ExceptionHandler;
+import com.codename1.backend.annotations.GetMapping;
+import com.codename1.backend.annotations.PathVariable;
+import com.codename1.backend.annotations.ResponseStatus;
+import com.codename1.backend.annotations.RestController;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.Map;
+
+// tag::backend-web-exception-handler[]
+@RestController
+public class NotesWithHandler {
+    private final Map<Long, NoteView> notes = new HashMap<Long, NoteView>();
+
+    @GetMapping("/notes/{id}")
+    public NoteView note(@PathVariable("id") long id) {
+        NoteView note = notes.get(id);
+        if (note == null) {
+            throw new NoteMissing(id);
+        }
+        return note;
+    }
+
+    @ExceptionHandler(NoteMissing.class)
+    @ResponseStatus(404)
+    public Map<String, String> missing(NoteMissing e) {
+        return Collections.singletonMap("error", e.getMessage());
+    }
+}
+// end::backend-web-exception-handler[]

docs/demos/backend/src/main/java/com/codenameone/developerguide/backend/advice/Tag.java

@@ -0,0 +1,30 @@
+/*
+ * Copyright (c) 2012, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+package com.codenameone.developerguide.backend.advice;
+
+import com.codename1.backend.validation.Size;
+
+/** A collection element the validation example checks one by one. */
+public class Tag {
+    @Size(min = 1, max = 20) public String name;
+}

docs/demos/backend/src/main/java/com/codenameone/developerguide/backend/advice/ValidatedNotes.java

@@ -0,0 +1,56 @@
+/*
+ * Copyright (c) 2012, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+package com.codenameone.developerguide.backend.advice;
+
+import com.codename1.backend.annotations.GetMapping;
+import com.codename1.backend.annotations.PostMapping;
+import com.codename1.backend.annotations.RequestBody;
+import com.codename1.backend.annotations.RequestParam;
+import com.codename1.backend.annotations.RestController;
+import com.codename1.backend.validation.Min;
+import com.codename1.backend.validation.Valid;
+import java.util.ArrayList;
+import java.util.List;
+
+/** The controller half of the validation example. */
+@RestController
+public class ValidatedNotes {
+    private final List<NoteView> notes = new ArrayList<NoteView>();
+
+    // tag::backend-web-validation-controller[]
+    @PostMapping("/notes")
+    public NoteView create(@Valid @RequestBody NewNote note) {
+        NoteView saved = new NoteView();
+        saved.id = notes.size() + 1;
+        saved.title = note.title;
+        notes.add(saved);
+        return saved;
+    }
+
+    @GetMapping("/notes")
+    public List<NoteView> page(@RequestParam("page") @Min(1) int page) {
+        int from = Math.min((page - 1) * 20, notes.size());
+        return new ArrayList<NoteView>(notes.subList(from, Math.min(from + 20, notes.size())));
+    }
+    // end::backend-web-validation-controller[]
+}