wip(note): initial Note ideas #697

$source=d328613dfd99b68b90943ed7b688ac81ea18a413$

main/objectos/way/AppShutdownHook.java

@@ -24,6 +24,21 @@
 
 final class AppShutdownHook implements App.ShutdownHook {
 
+  record Notes(
+      Note.Ref1<Object> registered,
+      Note.Ref1<Object> ignored
+  ) {
+    static Notes create() {
+      Class<?> s;
+      s = App.ShutdownHook.class;
+
+      return new Notes(
+          Note.Ref1.create(s, "Registered", Note.INFO),
+          Note.Ref1.create(s, "Ignored", Note.INFO)
+      );
+    }
+  }
+
   private final List<Object> hooks = Util.createList();
 
   private final Job job;

main/objectos/way/Css.java

@@ -41,7 +41,7 @@ public final class Css {
    * Generates a style sheet by scanning Java class files for predefined CSS
    * utility class names.
    */
-  public sealed interface Generator permits CssGenerator {}
+  sealed interface Generator permits CssGenerator {}
 
   /**
    * A style sheet generation option.

main/objectos/way/Note.java

@@ -0,0 +1,202 @@
+/*
+ * Copyright (C) 2023-2024 Objectos Software LTDA.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package objectos.way;
+
+import java.util.Objects;
+
+/**
+ * The <strong>Objectos Notes</strong> main class.
+ */
+public sealed abstract class Note {
+
+  public static final class Int1 extends Note {
+    Int1(Class<?> source, String key, Marker marker) {
+      super(source, key, marker);
+    }
+  }
+
+  public static final class Int2 extends Note {
+    Int2(Class<?> source, String key, Marker marker) {
+      super(source, key, marker);
+    }
+  }
+
+  public static final class Int3 extends Note {
+    Int3(Class<?> source, String key, Marker marker) {
+      super(source, key, marker);
+    }
+  }
+
+  public static final class Long1 extends Note {
+    Long1(Class<?> source, String key, Marker marker) {
+      super(source, key, marker);
+    }
+  }
+
+  public static final class Long2 extends Note {
+    Long2(Class<?> source, String key, Marker marker) {
+      super(source, key, marker);
+    }
+  }
+
+  public static final class Ref0 extends Note {
+    Ref0(Class<?> source, String key, Marker marker) {
+      super(source, key, marker);
+    }
+  }
+
+  public static final class Ref1<T1> extends Note {
+    Ref1(Class<?> source, String key, Marker marker) {
+      super(source, key, marker);
+    }
+
+    public static <T1> Ref1<T1> create(Class<?> source, String key, Marker marker) {
+      return new Ref1<>(source, key, marker);
+    }
+  }
+
+  public static final class Ref2<T1, T2> extends Note {
+    Ref2(Class<?> source, String key, Marker marker) {
+      super(source, key, marker);
+    }
+  }
+
+  public static final class Ref3<T1, T2, T3> extends Note {
+    Ref3(Class<?> source, String key, Marker marker) {
+      super(source, key, marker);
+    }
+  }
+
+  public sealed interface Marker {}
+
+  /**
+   * The TRACE level is typically used for events that are for detailed internal
+   * workings.
+   */
+  public static final Marker TRACE = Level.TRACE;
+
+  /**
+   * The DEBUG level is typically used for events that are for debugging
+   * purposes.
+   */
+  public static final Marker DEBUG = Level.DEBUG;
+
+  /**
+   * The INFO level is typically used for events that are informational.
+   */
+  public static final Marker INFO = Level.INFO;
+
+  /**
+   * The WARN level is typically used for events demanding attention.
+   */
+  public static final Marker WARN = Level.WARN;
+
+  /**
+   * The ERROR level is typically used for events demanding immediate attention.
+   */
+  public static final Marker ERROR = Level.ERROR;
+
+  /**
+   * Represents the severity of a `Note`. They may be used by `NoteSink`
+   * instances to limit which notes are actually sent.
+   */
+  enum Level implements Marker {
+    TRACE,
+
+    DEBUG,
+
+    INFO,
+
+    WARN,
+
+    ERROR;
+  }
+
+  public static class NoOpSink implements Sink {
+
+    @Override
+    public boolean isEnabled(Note note) {
+      return false;
+    }
+
+    @Override
+    public void send(Int1 note, int value) {}
+
+    @Override
+    public void send(Int2 note, int value1, int value2) {}
+
+    @Override
+    public void send(Int3 note, int value1, int value2, int value3) {}
+
+    @Override
+    public void send(Long1 note, long value) {}
+
+    @Override
+    public void send(Long2 note, long value1, long value2) {}
+
+    @Override
+    public void send(Ref0 note) {}
+
+    @Override
+    public <T1> void send(Ref1<T1> note, T1 value) {}
+
+    @Override
+    public <T1, T2> void send(Ref2<T1, T2> note, T1 value1, T2 value2) {}
+
+    @Override
+    public <T1, T2, T3> void send(Ref3<T1, T2, T3> note, T1 value1, T2 value2, T3 value3) {}
+
+  }
+
+  public interface Sink {
+
+    boolean isEnabled(Note note);
+
+    void send(Int1 note, int value);
+
+    void send(Int2 note, int value1, int value2);
+
+    void send(Int3 note, int value1, int value2, int value3);
+
+    void send(Long1 note, long value);
+
+    void send(Long2 note, long value1, long value2);
+
+    void send(Ref0 note);
+
+    <T1> void send(Ref1<T1> note, T1 value);
+
+    <T1, T2> void send(Ref2<T1, T2> note, T1 value1, T2 value2);
+
+    <T1, T2, T3> void send(Ref3<T1, T2, T3> note, T1 value1, T2 value2, T3 value3);
+
+  }
+
+  final String source;
+
+  final String key;
+
+  final Marker marker0;
+
+  Note(Class<?> source, String key, Marker marker) {
+    this.source = source.getCanonicalName();
+
+    this.key = Objects.requireNonNull(key, "key == null");
+
+    marker0 = Objects.requireNonNull(marker, "marker == null");
+  }
+
+}

main/objectos/way/UtilBaseCollection.java

@@ -31,7 +31,7 @@
  *
  * @param <E> type of the elements in this collection
  */
-public abstract class UtilBaseCollection<E> implements Collection<E> {
+abstract class UtilBaseCollection<E> implements Collection<E> {
 
   /**
    * Sole constructor

main/objectos/way/UtilUnmodifiableCollection.java

@@ -27,66 +27,66 @@
  *
  * @param <E> type of the elements in this collection
  */
-public abstract class UtilUnmodifiableCollection<E> extends UtilBaseCollection<E> {
+abstract class UtilUnmodifiableCollection<E> extends UtilBaseCollection<E> {
 
-	/**
-	 * Sole constructor.
-	 */
-	protected UtilUnmodifiableCollection() {}
+  /**
+   * Sole constructor.
+   */
+  protected UtilUnmodifiableCollection() {}
 
-	/**
-	 * This operation is not supported.
-	 *
-	 * <p>
-	 * This method performs no operation other than throw an
-	 * {@link UnsupportedOperationException}.
-	 *
-	 * @param e
-	 *        ignored (this operation is not supported)
-	 *
-	 * @return this method does not return as it always throw an exception
-	 *
-	 * @throws UnsupportedOperationException
-	 *         always
-	 */
-	@Override
-	public final boolean add(E e) {
-		throw new UnsupportedOperationException();
-	}
+  /**
+   * This operation is not supported.
+   *
+   * <p>
+   * This method performs no operation other than throw an
+   * {@link UnsupportedOperationException}.
+   *
+   * @param e
+   *        ignored (this operation is not supported)
+   *
+   * @return this method does not return as it always throw an exception
+   *
+   * @throws UnsupportedOperationException
+   *         always
+   */
+  @Override
+  public final boolean add(E e) {
+    throw new UnsupportedOperationException();
+  }
 
-	/**
-	 * This operation is not supported.
-	 *
-	 * <p>
-	 * This method performs no operation other than throw an
-	 * {@link UnsupportedOperationException}.
-	 *
-	 * @param c
-	 *        ignored (this operation is not supported)
-	 *
-	 * @return this method does not return as it always throw an exception
-	 *
-	 * @throws UnsupportedOperationException
-	 *         always
-	 */
-	@Override
-	public final boolean addAll(Collection<? extends E> c) {
-		throw new UnsupportedOperationException();
-	}
+  /**
+   * This operation is not supported.
+   *
+   * <p>
+   * This method performs no operation other than throw an
+   * {@link UnsupportedOperationException}.
+   *
+   * @param c
+   *        ignored (this operation is not supported)
+   *
+   * @return this method does not return as it always throw an exception
+   *
+   * @throws UnsupportedOperationException
+   *         always
+   */
+  @Override
+  public final boolean addAll(Collection<? extends E> c) {
+    throw new UnsupportedOperationException();
+  }
 
-	/**
-	 * This operation is not supported.
-	 *
-	 * <p>
-	 * This method performs no operation other than throw an
-	 * {@link UnsupportedOperationException}.
-	 *
-	 * @throws UnsupportedOperationException
-	 *         always
-	 */
-	@Override
-	public final void clear() {
-		throw new UnsupportedOperationException();
-	}
+  /**
+   * This operation is not supported.
+   *
+   * <p>
+   * This method performs no operation other than throw an
+   * {@link UnsupportedOperationException}.
+   *
+   * @throws UnsupportedOperationException
+   *         always
+   */
+  @Override
+  public final void clear() {
+    throw new UnsupportedOperationException();
+  }
 
 }