Use Utility Class Methods as Extensions

[EotT123]

This PR depends on #656.

---

Using Utility Class Methods as Extensions

Methods in utility classes are often good candidates to be used as extension methods. However, since these methods are not annotated, they cannot be used directly as extension methods.

Rather than manually converting all those methods into extensions, which can be time-consuming and error-prone, you can leverage Manifold's built-in functionality to automate this process. By specifying the utility class as a parameter to the @ExtensionSource annotation, you can easily incorporate its methods as extension methods for the target type.

Basic Usage

Suppose you want to use methods from the org.apache.commons.lang3.StringUtils class as extension methods for java.lang.String. You can do this with the following code:

package extensions.java.lang.String;

import java.org.apache.commons.lang3.StringUtils;
import manifold.ext.rt.api.Extension;
import manifold.ext.rt.api.ExtensionSource;

@Extension
@ExtensionSource( source = StringUtils.class )
public class MyStringExt {
    // Additional extension methods can be added here
}

With this approach, all public, static methods from the StringUtils class that take a String as their first parameter will be automatically available as extension methods for String objects.
Any methods that conflict with existing methods in the String class (i.e., methods with the same signature) will be excluded by default.

Overriding Existing Methods

If you want to override existing methods (i.e., make the methods from the utility class replace the methods already present on the target object), you can set the overrideExistingMethods attribute to true:

@ExtensionSource( source = Files.class, overrideExistingMethods = true )

Granular Control Over Included and Excluded Methods

You can further control which methods are included or excluded by specifying the method signatures you want to include or exclude. This is achieved using the type and methods attributes in the @ExtensionSource annotation.

For example, to include (or exclude) only specific methods from StringUtils, you can specify the INCLUDE or EXCLUDE types and provide method signatures:

@ExtensionSource( 
    source = StringUtils.class,
    overrideExistingMethods = true,
    type = ExtensionMethodType.INCLUDE, // <-- change to EXCLUDE to exclude specified methods
    methods = {
        @MethodSignature( name = "substring", paramTypes = { String.class, int.class } )
        // others
    } )