update java recipes to be cfml dev orientated

Author: zspitzer

docs/recipes/component-getclass-method.md

@@ -2,23 +2,19 @@
 {
   "title": "getClass() Method for Components",
   "id": "component-getclass-method",
-  "description": "This document explains the getClass() method for CFML components that implement Java interfaces, enabling seamless Java interoperability.",
+  "since": "7.0",
+  "description": "Get the Java class of a component that implements a Java interface.",
   "keywords": [
     "getClass",
     "component",
     "java",
-    "proxy",
-    "interface",
-    "interoperability"
+    "interface"
   ],
   "related": [
     "tag-component",
-    "function-createdynamicproxy",
-    "new-operator",
-    "developing-with-lucee-server"
+    "function-createdynamicproxy"
   ],
   "categories": [
-    "core",
     "component",
     "java"
   ]
@@ -27,49 +23,38 @@
 
 # getClass() Method for Components
 
-In Lucee, components that implement Java interfaces can use the `getClass()` method to obtain the Java class representation. 
+When a component implements a Java interface, you can call `getClass()` to get the underlying Java class. Useful when Java code needs to inspect your component's type.
 
-This method automatically creates (if needed) a dynamic proxy and returns the proxy's class, enabling seamless Java interoperability without explicit proxy creation.
+**Java terms:** A *proxy* is a wrapper object that Lucee creates to make your component look like a real Java class. *Reflection* is when Java code inspects objects at runtime to discover their methods and properties - many frameworks use this for dependency injection, serialization, and type checking.
 
-*Available since Lucee 7.0*
-
-## Basic Usage
-
-When called on a component that implements Java interfaces, `getClass()` returns the Java class of the dynamic proxy:
+## Usage
 
 ```lucee
-mymap = new component implements="java:java.util.Map" {
-    // component implementation
+myMap = new component implements="java:java.util.Map" {
+	// implement Map methods...
 };
 
-classInfo = mymap.getClass(); // Returns proxy class
-dump(classInfo);
+// Get the Java class
+cls = myMap.getClass();
+dump( cls.getName() ); // something like "lucee.runtime.proxy.Map$..."
 ```
 
-This is equivalent to the more verbose:
+This is shorthand for:
 
 ```lucee
-classInfo = createDynamicProxy(mymap).getClass();
+cls = createDynamicProxy( myMap ).getClass();
 ```
 
-## Method Resolution Order
+## Resolution Order
 
-The `getClass()` method follows a specific resolution order:
-
-1. **Custom Function**: If the component defines a function named "getClass", that function is called
-2. **Property Getter**: If the component has a property named "class" with `accessor=true`, the getter is used
-3. **Default Behavior**: Otherwise, a dynamic proxy is created and `proxy.getClass()` is returned
+1. If the component has a `getClass()` function, that's called
+2. If the component has a `class` property with accessors, the getter is used
+3. Otherwise, returns the Java proxy class
 
 ## Requirements
 
-- The component must implement at least one Java interface
-- The method only applies to components, not regular objects
-
-## Use Cases
+The component must implement at least one Java interface using `implements="java:..."` syntax.
 
-This feature is particularly useful for:
+## When You'd Use This
 
-- Java library integration where class information is needed
-- Reflection operations on component proxies
-- Framework development requiring class metadata
-- Simplified Java interoperability code
+Some Java libraries inspect the class of objects you pass them - to check types, discover methods, or register handlers. Without `getClass()`, you'd need to manually create a proxy first. This makes it seamless.

docs/recipes/convert-a-cfml-func-to-java.md

@@ -1,8 +1,8 @@
 <!--
 {
-  "title": "Convert a CFML Function/Component to use in Java",
+  "title": "Using CFML Functions and Components in Java",
   "id": "convert-a-cfml-func-to-java",
-  "description": "Learn how to convert user-defined functions or components in Lucee to use them in Java. This guide demonstrates how to define components to implement Java interfaces, pass components to Java methods, explicitly define interfaces, and use the onMissingMethod feature. It also shows how to convert user-defined functions to Java lambdas.",
+  "description": "Pass CFML components and functions to Java code - implement Java interfaces with CFCs, use functions as Java lambdas.",
   "since": "6.0",
   "keywords": [
     "conversion",
@@ -13,74 +13,81 @@
     "lambda",
     "Lucee"
   ],
-  "categories":[
+  "categories": [
     "java"
   ],
   "related": [
-    "tag-component"
+    "tag-component",
+    "dynamic-proxy-enhancements",
+    "java-explicit-casting"
   ]
 }
 -->
 
-# Convert a CFML Function/Component to use in Java
+# Using CFML Functions and Components in Java
 
-Lucee allows you to convert user-defined functions or components so you can use them in Java.
+Many Java libraries accept objects that implement specific *interfaces* - contracts defining what methods an object must have. Lucee lets you pass CFML components and functions directly to Java code.
 
-## Component to Java Class
+**Java terms:** A *Java interface* defines method signatures a class must implement (like a blueprint). A *lambda* is a shorthand for a single-method interface - Java 8+ uses these heavily for callbacks and streaming APIs.
 
-You simply add all functions defined for a Java interface to a component like this:
+## Component to Java Interface
+
+Implement the interface's methods in your component:
 
 ```lucee
-// Component that implements all methods from interface CharSequence
+// MyString.cfc - implements CharSequence interface
 component {
-    function init(String str) {
-        variables.str = reverse(arguments.str);
-    }
-    function length() {
-        SystemOutput("MyString.length:" & str.length(), 1, 1);
-        return str.length();
-    }
-    // ... more functions here
+	function init( String str ) {
+		variables.str = reverse( arguments.str );
+	}
+
+	function length() {
+		return str.length();
+	}
+
+	// ... implement other CharSequence methods
 }
 ```
 
-### Pass to Java
-
-Then you can pass that component to a Java method needing a specific interface/class.
+Then pass it to Java methods expecting that interface:
 
 ```lucee
-// This class has a method that takes as an argument a CharSequence.
-// This way we can force Lucee to convert/wrap our component to that interface.
-HashUtil = createObject("java", "lucee.commons.digest.HashUtil");
+HashUtil = createObject( "java", "lucee.commons.digest.HashUtil" );
+cfc = new MyString( "Susi Sorglos" );
 
-// This component implements all necessary functions for the CharSequence
-cfc = new MyString("Susi Sorglos");
-
-// Calling the method HashUtil.create64BitHashAsString(CharSequence cs) with our component as an argument
-hash = HashUtil.create64BitHashAsString(cfc);
-dump(hash);
+// HashUtil.create64BitHashAsString() expects CharSequence - Lucee converts automatically
+hash = HashUtil.create64BitHashAsString( cfc );
+dump( hash );
 ```
 
-### Explicit Definition and "onMissingMethod"
+### Using implementsJava and onMissingMethod
 
-Of course, you can also define the interface you want to implement explicitly and you can use “onMissingMethod” so you do not have to implement every single function separately.
+Declare the interface explicitly and handle method calls dynamically:
 
 ```lucee
 component implementsJava="java.util.List" {
-    function onMissingMethod(name, args) {
-        if (name == "size") return 10;
-        throw "method #name# is not supported!";
-    }
+	function onMissingMethod( name, args ) {
+		if ( name == "size" ) return 10;
+		throw "method #name# is not supported!";
+	}
 }
 ```
 
-## User-Defined Function to Java (as Lambda)
+See [[java-explicit-casting]] for when you need to cast components to specific interfaces.
+
+## Functions as Java Lambdas
 
-Functions get converted to a Lambda interface when the interface matches automatically. You can do the same with regular functions, but here the conversion happens when passing to Java.
+When a Java method expects a *functional interface* (an interface with one method), you can pass a CFML function directly. Lucee converts it automatically:
 
 ```lucee
-numeric function echoInt(numeric i) {
-    if (i == 1) throw "Test output!!!";
-    return i * 2;
+numeric function doubleIt( numeric i ) {
+	return i * 2;
 }
+
+// Java's IntStream.map() expects IntUnaryOperator (one method: int applyAsInt(int))
+import java.util.stream.IntStream;
+result = IntStream::of( 1, 2, 3 ).map( doubleIt ).sum();
+dump( result ); // 12 (2 + 4 + 6)
 ```
+
+See [[java-in-functions-and-closures]] for more on Java lambdas and the `type="java"` function attribute.

docs/recipes/dynamic-proxy-enhancements.md

@@ -1,8 +1,9 @@
 <!--
 {
-  "title": "Dynamic Proxy Enhancements in Lucee 7",
+  "title": "Dynamic Proxy Enhancements",
   "id": "dynamic-proxy-enhancements",
-  "description": "Learn about the improvements to dynamic proxy creation in Lucee 7, including automatic inclusion of component functions and properties when implementing Java interfaces.",
+  "since": "7.0",
+  "description": "Lucee 7 improvements to dynamic proxy creation - all component functions and properties are now always included when implementing Java interfaces.",
   "keywords": [
     "dynamic proxy",
     "java",
@@ -24,129 +25,85 @@
 }
 -->
 
-# Dynamic Proxy Enhancements in Lucee 7
+# Dynamic Proxy Enhancements
 
-All component functions and properties are now always included in dynamic proxies, making Java interoperability more predictable.
+When you pass a CFML component to Java code, Lucee creates a *proxy* - a wrapper that makes your component look like a Java object. In Lucee 7, proxies now include **all** your component's functions and properties, not just the interface methods.
 
-## What Changed in Lucee 7
+**Java terms:** A *Java interface* is a contract defining method signatures a class must implement (like CFML's `implements` attribute). A *proxy* wraps your component so Java sees it as implementing that interface.
 
-### Component Functions and Properties Always Included
+## What Changed
 
-In previous versions, when creating a dynamic proxy from a component that implements Java interfaces, not all component functions and properties were consistently included in the proxy. Lucee 7 ensures that **all component functions and properties are always included** in the dynamic proxy.
+Previously, custom methods you added beyond the interface weren't consistently available through the proxy. Now they always are (LDEV-5421).
 
-This enhancement (LDEV-5421) makes dynamic proxies behave more predictably and eliminates subtle issues where component methods might not be accessible through the proxy.
-
-## Basic Usage
-
-When you create a component that implements a Java interface, you can use `createDynamicProxy()` to get a Java proxy object:
+## Example
 
 ```cfml
-// Define a component implementing java.util.Map
 myComponent = new component implements="java:java.util.Map" {
-
-	function size(){
-		return 42;
-	}
-
-	function isEmpty(){
-		return false;
-	}
+	function size() { return 42; }
+	function isEmpty() { return false; }
+	function get( key ) { return "value"; }
+	function put( key, value ) { return null; }
+	// ... other Map methods
 
 	// Custom function (not part of Map interface)
-	function customMethod(){
-		return "This is now always included in the proxy!";
-	}
-
-	// Additional required Map methods...
-	function get( key ){
-		return "value";
+	function customMethod() {
+		return "Now always included in the proxy!";
 	}
-
-	function put( key, value ){
-		return null;
-	}
-
-	// ... other Map interface methods
 };
 
-// Create the dynamic proxy
 proxy = createDynamicProxy( myComponent, [ "java.util.Map" ] );
 
-// All component methods are accessible through the proxy
-systemOutput( proxy.size() );	// 42
-systemOutput( proxy.customMethod() );	// Works in Lucee 7!
+systemOutput( proxy.size() );          // 42
+systemOutput( proxy.customMethod() );  // Works in Lucee 7!
 ```
 
-## Automatic Proxy Creation with getClass()
+## getClass() Shorthand
 
-Lucee 7 also introduces the ability to call `.getClass()` directly on components that implement Java interfaces, automatically creating a dynamic proxy if needed:
+Components with `implements="java:..."` can call `.getClass()` directly - Lucee creates the proxy automatically:
 
 ```cfml
 myComponent = new component implements="java:java.util.Map" {
-	function size(){
-		return 42;
-	}
-	// ... other methods
+	// ... methods
 };
 
-// New in Lucee 7 - automatic proxy creation
 classInfo = myComponent.getClass();
 
-// Previously required explicit proxy creation:
+// Equivalent to:
 // classInfo = createDynamicProxy( myComponent, [ "java.util.Map" ] ).getClass();
 ```
 
-See [[component-getclass-method]] for more details on this feature.
-
-## Use Cases
+See [[component-getclass-method]] for details.
 
-These enhancements are particularly valuable when:
+## Runnable Example
 
-- **Building Java library integrations** - Your component methods are reliably accessible through the proxy
-- **Extending Java interfaces** - Add custom functionality beyond the interface contract
-- **Framework development** - Create components that implement Java interfaces with additional CFML-specific methods
-- **Working with callbacks** - Pass components to Java libraries that expect interface implementations
-
-## Example: Implementing java.lang.Runnable
+A practical use case - implementing Java's `Runnable` interface to run code in a thread:
 
 ```cfml
-// Create a component implementing Runnable
 task = new component implements="java:java.lang.Runnable" {
-
 	variables.executionCount = 0;
 
-	function run(){
+	function run() {
 		variables.executionCount++;
 		systemOutput( "Task executed ##variables.executionCount## times" );
 	}
 
-	// Custom method to check execution count
-	function getExecutionCount(){
+	// Custom method - now accessible through proxy
+	function getExecutionCount() {
 		return variables.executionCount;
 	}
 };
 
-// Create proxy and pass to Java's ExecutorService
 proxy = createDynamicProxy( task, [ "java.lang.Runnable" ] );
 
-// Create a Java thread
 thread = createObject( "java", "java.lang.Thread" ).init( proxy );
 thread.start();
 thread.join();
 
-// Access custom methods through the original component
 systemOutput( "Total executions: " & task.getExecutionCount() );
 ```
 
-## Key Benefits
-
-1. **Predictable behavior** - All component methods are consistently available through the proxy
-2. **Simplified code** - Automatic proxy creation with `.getClass()`
-3. **Better Java integration** - Seamlessly mix CFML and Java functionality
-4. **Enhanced flexibility** - Add custom methods beyond interface requirements
-
-## See Also
+## When You'd Use This
 
-- [[component-getclass-method]] - Using getClass() for automatic proxy creation
-- [[java-class-interaction]] - General Java interoperability in Lucee
-- [[function-createdynamicproxy]] - createDynamicProxy() function reference
+- **Java library callbacks** - pass components to Java code expecting interface implementations
+- **Custom methods on proxies** - add CFML-specific helpers alongside interface methods
+- **Threading** - implement Runnable, Callable, or other Java concurrency interfaces