What restrictions should there be on configuration objects' classes?

[ljnelson]

I know that @m0mus likes options so here are options.

Consider a hypothetical loader API sketch:

// this is a sketch, not a proposal
MyConfigurationRelatedObject o =
    someLoader.load(Class<MyConfigurationRelatedObject> c,
                    ...maybe other addressing information...);

(For this discussion I'm assuming that c.isInterface() MUST return true (see #122). If that changes I'll update the options here.)

What MUST be true of c? Possible assertions in addition to assert c.isInterface() include:

1. assert c.getTypeParameters().length == 0; (i.e. the interface is non-generic)
2. assert !c.isLocalClass();
3. assert !c.isAnonymousClass();
4. assert !c.isMemberClass();
5. assert c.getInterfaces().length == 0; (i.e. no subtyping)
6. assert !c.getName().startsWith("java."); (or something similar; i.e. rule out c being something stupid like java.lang.Iterable; this only applies if (7) is not in effect)
7. assert c.getAnnotation(SomeJakartaConfigMarkerAnnotation.class) != null; (i.e. have some way of marking this interface as a special interface)
8. assert java.lang.reflect.Modifier.isPublic(c.getModifiers()); (i.e. prohibit package-protected interfaces)
9. assert c.getDeclaredMethods().length > 0; (i.e. rule out "marker" interfaces)
10. (There is no 10.)

What MUST be true of o.getClass()? Possible assertions include:

11. assert o.getClass().getDeclaredAnnotation(SomeJakartaConfigMarkerAnnotation.class) != null; (i.e. the implementation is directly annotated in some way to indicate it's "one of ours")
12. assert o.getClass().isSynthetic(); (i.e. require that the implementation have its synthetic flag set)
13. assert o.getClass().getSuperclass() == Object.class (i.e. require that the implementation have no supertypes other than Object)

Then, regarding any method m declared by c, what MUST be true of m? Possible assertions include:

14. No assertions (i.e. methods that are impossible to implement sensibly are backed by an implementation that throws UnsupportedOperationException or something similar to be figured out later)
15. assert m.getReturnType() != void.class && m.getReturnType() != Void.class; (i.e. methods with void or Void return types are not permitted)
16. assert m.getParameterCount() == 0; (i.e. methods that declare parameters are not permitted)
17. assert !java.lang.reflect.Modifier.isStatic(m.getModifiers()); (i.e. static methods are not permitted)
18. assert !m.isDefault(); (i.e. default interface methods are not permitted)
19. assert m.getTypeParameters().length == 0; (i.e. generic methods are not permitted)
20. assert m.getExceptionTypes().length == 0; (i.e. methods that throw exceptions are not permitted)

[ljnelson]

I (think I?) vote for the following set of assertions:

{ 4, 6, 7, 8, 9, 12, 19 }

[dmlloyd]

I would say { 1, 6, 12, 15, 16*, (maybe)18, 19, 20}. Here is my reasoning:

1. Reasoning about the behavior etc. of generic interfaces is going to be very complex to say the least. We can do that later (if ever).
2. Interfaces cannot be local classes by nature.
3. Interfaces cannot be anonymous classes by nature.
4. It doesn't really matter if a configuration interface is a member class; in fact for simple use cases, this might be preferable (for example I might nestle the interface right inside the class which uses it).
5. We should support subtyping; this is one of the motivating factors for using interfaces in fact. This allows common shapes to be reused in conjunction with multiple inheritance, which is useful.
6. I think this probably does no harm and might avoid common bugs.
7. It just doesn't seem necessary; less boilerplate is better.
8. This probably doesn't matter so much; it's mostly an implementation concern. We can (for example) support non-public interfaces in an "SE friendly" manner by providing a variation of the factory method which accepts a MethodHandles.Lookup instance.
9. In light of 5, I think empty interfaces are OK (they might aggregate two or more other interfaces). And, honestly, a completely empty configuration interface is really pretty harmless too, and might even be a valid state (imagining, for example, a user that is steadily refactoring their code and removes the last configuration method before adding a new one).
10. There is no 10!
11. Well, I really have no strong feelings here at the moment. Maybe I will later.
12. I agree, synthetic classes (and methods) should be marked as synthetic.
13. Implementations should be free to be as flexible with implementation strategy as we can permit; there doesn't seem to be a good reason to restrict the class hierarchy of the implementation.
14. I don't quite understand this one, tbh.
15. This seems reasonable; it's hard to imagine a use case for a void configuration property.
16. Agreed for now. It might be nice later on to permit shortcuts for things; for example instead of just Map<String, Foo> foos() maybe we want to allow Foo foo(String name) instead/in addition in the future.
17. I think we should allow static methods (and fields); they don't really have anything to do with anything that we (as specifiers or as implementers) would need to care about.
18. I marked this one as a "maybe". One could argue that we ignore default methods and let users throw in whatever behavior they want for them. However, it gets complex when default methods overload or override one another in the interface hierarchy, so it might be too hard for implementations to sensibly decide whether a given method is a configuration method that it must implement or a default method that it must ignore.
19. I agree that generic configuration property methods should be disallowed. But if the user supplies a static method which is generic, that's probably OK.
20. I think this makes sense since the overall contract that we've been discussion thus far implies (to me) that we should have populated the configuration objects eagerly upon construction, and thus there is no need for run time exceptions once it is built.

[ljnelson]

(Just skimming; wow, you're right, there is no 10 (thanks, Github markdown helpfulness!) and (2) and (3) are just results of me plowing through the relevant methods. Nice catches.)

[radcortez]

{1, 6, 12, 15, 16, 19, 20}

.14 Can you provide an example of a method you think we cannot implement?

[ljnelson]

Any interface method with one or more parameters:

public interface MyStuff {
  public long getTimeout(TimeUnit unit);
  public String getGreeting(Locale locale);
  public Cake makeCake(Egg[] eggs, Milk milk, Sugar sugar, Flour flour, Object... other);
}