From ce2e33d6bd1f19b1bfca89801ab949be3f10d058 Mon Sep 17 00:00:00 2001
From: michaeloffner <michaeloffner@users.noreply.github.com>
Date: Thu, 27 Jun 2024 10:51:05 +0200
Subject: [PATCH] add recipe

---
 docs/recipes/java-explicit-casting.md | 67 +++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 docs/recipes/java-explicit-casting.md

diff --git a/docs/recipes/java-explicit-casting.md b/docs/recipes/java-explicit-casting.md
new file mode 100644
index 000000000..6e3fcbb73
--- /dev/null
+++ b/docs/recipes/java-explicit-casting.md
@@ -0,0 +1,67 @@
+<!--
+{
+  "title": "Java - Explicit Casting of a Component to a Specific Interface",
+  "id": "java-explicit-casting",
+  "since": "6.0", 
+  "categories": [
+    "java"
+  ],
+  "description": "Shows how to explicitly cast a component to a specific interface.",
+  "keywords": [
+    "java",
+    "cast",
+    "convert",
+    "method"
+  ]
+}
+-->
+
+# Java - Explicit Casting of a Component to a Specific Interface
+
+This guide demonstrates how to explicitly cast a component to a specific interface in Lucee.
+
+## Implicit Casting
+Lucee supports implicit casting by passing a component to a method where the method argument is of a specific type. For example:
+
+```
+cs = new component implementsJava="java.lang.CharSequence" {
+  variables.text = "en_us";
+
+  public function onMissingMethod(missingMethodName, missingMethodArguments) {
+    if ("toString" == missingMethodName) return variables.text;
+    else throw "method #missingMethodName# not supported yet!";
+  }
+};
+// setLocale expects a String as argument PageContext.setLocale(java.lang.String)
+getPageContext().setLocale(cs);
+```
+
+In this example, Lucee implicitly finds a matching method and converts the component to a class implementing the `java.lang.CharSequence` interface.
+
+## Explicit Casting
+Sometimes, implicit casting can be problematic if Lucee cannot make the correct fit, or if a method is overloaded and you need to specify which method to use. 
+
+For instance, the `PageContext` class has two `setLocale` methods:
+- `setLocale(java.lang.String): void`
+- `setLocale(java.util.Locale): void`
+
+To ensure the correct method is called, it is better to use explicit casting. Here's the modified example:
+
+```run
+cs = new component implementsJava="java.lang.CharSequence" {
+  variables.text = "en_us";
+
+  public function onMissingMethod(missingMethodName, missingMethodArguments) {
+    if ("toString" == missingMethodName) return variables.text;
+    else throw "method #missingMethodName# not supported yet!";
+  }
+};
+// Explicitly cast to java.lang.CharSequence
+obj = JavaCast("java.lang.CharSequence", cs);
+dump(obj);
+
+// Use the CharSequence object
+getPageContext().setLocale(obj);
+```
+
+In this example, we first cast the component to `java.lang.CharSequence` (the base interface for `String`), then call `setLocale`. With this explicit casting, Lucee is able to link the correct method.