objectos.way.Note Maven / Gradle / Ivy
/*
* 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;
/**
* The Objectos Notes main interface.
*/
public sealed interface Note {
/**
* A note that takes one {@code int} argument.
*/
sealed interface Int1 extends Note permits NoteImpl {
/**
* Creates a new {@code Int1} instance with the specified source, key and
* marker.
*
* @param source
* a class instance whose canonical name will be used as the source
* of the note
* @param key
* the key of the note
* @param marker
* the marker to associate to the note
*
* @return a newly create note instance
*/
static Int1 create(Class source, String key, Marker marker) {
return new NoteImpl(source, key, marker);
}
/**
* Creates a new {@code Int1} instance with the specified source, key and
* marker.
*
* @param source
* the source of the note
* @param key
* the key of the note
* @param marker
* the marker to associate to the note
*
* @return a newly create note instance
*/
static Int1 create(String source, String key, Marker marker) {
return new NoteImpl(source, key, marker);
}
}
/**
* A note that takes two {@code int} arguments.
*/
sealed interface Int2 extends Note permits NoteImpl {
/**
* Creates a new {@code Int2} instance with the specified source, key and
* marker.
*
* @param source
* a class instance whose canonical name will be used as the source
* of the note
* @param key
* the key of the note
* @param marker
* the marker to associate to the note
*
* @return a newly create note instance
*/
static Int2 create(Class source, String key, Marker marker) {
return new NoteImpl(source, key, marker);
}
/**
* Creates a new {@code Int2} instance with the specified source, key and
* marker.
*
* @param source
* the source of the note
* @param key
* the key of the note
* @param marker
* the marker to associate to the note
*
* @return a newly create note instance
*/
static Int2 create(String source, String key, Marker marker) {
return new NoteImpl(source, key, marker);
}
}
/**
* A note that takes three {@code int} arguments.
*/
sealed interface Int3 extends Note permits NoteImpl {
/**
* Creates a new {@code Int3} instance with the specified source, key and
* marker.
*
* @param source
* a class instance whose canonical name will be used as the source
* of the note
* @param key
* the key of the note
* @param marker
* the marker to associate to the note
*
* @return a newly create note instance
*/
static Int3 create(Class source, String key, Marker marker) {
return new NoteImpl(source, key, marker);
}
/**
* Creates a new {@code Int3} instance with the specified source, key and
* marker.
*
* @param source
* the source of the note
* @param key
* the key of the note
* @param marker
* the marker to associate to the note
*
* @return a newly create note instance
*/
static Int3 create(String source, String key, Marker marker) {
return new NoteImpl(source, key, marker);
}
}
/**
* A note that takes one {@code long} argument.
*/
sealed interface Long1 extends Note permits NoteImpl {
/**
* Creates a new {@code Long1} instance with the specified source, key and
* marker.
*
* @param source
* a class instance whose canonical name will be used as the source
* of the note
* @param key
* the key of the note
* @param marker
* the marker to associate to the note
*
* @return a newly create note instance
*/
static Long1 create(Class source, String key, Marker marker) {
return new NoteImpl(source, key, marker);
}
/**
* Creates a new {@code Long1} instance with the specified source, key and
* marker.
*
* @param source
* the source of the note
* @param key
* the key of the note
* @param marker
* the marker to associate to the note
*
* @return a newly create note instance
*/
static Long1 create(String source, String key, Marker marker) {
return new NoteImpl(source, key, marker);
}
}
/**
* A note that takes two {@code long} arguments.
*/
sealed interface Long2 extends Note permits NoteImpl {
/**
* Creates a new {@code Long2} instance with the specified source, key and
* marker.
*
* @param source
* a class instance whose canonical name will be used as the source
* of the note
* @param key
* the key of the note
* @param marker
* the marker to associate to the note
*
* @return a newly create note instance
*/
static Long2 create(Class source, String key, Marker marker) {
return new NoteImpl(source, key, marker);
}
/**
* Creates a new {@code Long2} instance with the specified source, key and
* marker.
*
* @param source
* the source of the note
* @param key
* the key of the note
* @param marker
* the marker to associate to the note
*
* @return a newly create note instance
*/
static Long2 create(String source, String key, Marker marker) {
return new NoteImpl(source, key, marker);
}
}
/**
* A note that takes no arguments.
*/
sealed interface Ref0 extends Note permits NoteImpl {
/**
* Creates a new {@code Ref0} instance with the specified source, key and
* marker.
*
* @param source
* a class instance whose canonical name will be used as the source
* of the note
* @param key
* the key of the note
* @param marker
* the marker to associate to the note
*
* @return a newly create note instance
*/
static Ref0 create(Class source, String key, Marker marker) {
return new NoteImpl(source, key, marker);
}
/**
* Creates a new {@code Ref0} instance with the specified source, key and
* marker.
*
* @param source
* the source of the note
* @param key
* the key of the note
* @param marker
* the marker to associate to the note
*
* @return a newly create note instance
*/
static Ref0 create(String source, String key, Marker marker) {
return new NoteImpl(source, key, marker);
}
}
/**
* A note that takes one object reference argument.
*
* @param the type of the note argument
*/
sealed interface Ref1 extends Note permits NoteImpl {
/**
* Creates a new {@code Ref1} instance with the specified source, key and
* marker.
*
* @param the type of the note argument
* @param source
* a class instance whose canonical name will be used as the source
* of the note
* @param key
* the key of the note
* @param marker
* the marker to associate to the note
*
* @return a newly create note instance
*/
@SuppressWarnings("unchecked")
static Ref1 create(Class source, String key, Marker marker) {
return (Ref1) new NoteImpl(source, key, marker);
}
/**
* Creates a new {@code Ref1} instance with the specified source, key and
* marker.
*
* @param the type of the note argument
* @param source
* the source of the note
* @param key
* the key of the note
* @param marker
* the marker to associate to the note
*
* @return a newly create note instance
*/
@SuppressWarnings("unchecked")
static Ref1 create(String source, String key, Marker marker) {
return (Ref1) new NoteImpl(source, key, marker);
}
}
/**
* A note that takes two object reference arguments.
*
* @param the type of the first note argument
* @param the type of the second note argument
*/
sealed interface Ref2 extends Note permits NoteImpl {
/**
* Creates a new {@code Ref2} instance with the specified source, key and
* marker.
*
* @param the type of the first note argument
* @param the type of the second note argument
* @param source
* a class instance whose canonical name will be used as the source
* of the note
* @param key
* the key of the note
* @param marker
* the marker to associate to the note
*
* @return a newly create note instance
*/
@SuppressWarnings("unchecked")
static Ref2 create(Class source, String key, Marker marker) {
return (Ref2) new NoteImpl(source, key, marker);
}
/**
* Creates a new {@code Ref2} instance with the specified source, key and
* marker.
*
* @param the type of the first note argument
* @param the type of the second note argument
* @param source
* the source of the note
* @param key
* the key of the note
* @param marker
* the marker to associate to the note
*
* @return a newly create note instance
*/
@SuppressWarnings("unchecked")
static Ref2 create(String source, String key, Marker marker) {
return (Ref2) new NoteImpl(source, key, marker);
}
}
/**
* A note that takes three object reference arguments.
*
* @param the type of the first note argument
* @param the type of the second note argument
* @param the type of the third note argument
*/
sealed interface Ref3 extends Note permits NoteImpl {
/**
* Creates a new {@code Ref3} instance with the specified source, key and
* marker.
*
* @param the type of the first note argument
* @param the type of the second note argument
* @param the type of the third note argument
* @param source
* a class instance whose canonical name will be used as the source
* of the note
* @param key
* the key of the note
* @param marker
* the marker to associate to the note
*
* @return a newly create note instance
*/
@SuppressWarnings("unchecked")
static Ref3 create(Class source, String key, Marker marker) {
return (Ref3) new NoteImpl(source, key, marker);
}
/**
* Creates a new {@code Ref3} instance with the specified source, key and
* marker.
*
* @param the type of the first note argument
* @param the type of the second note argument
* @param the type of the third note argument
* @param source
* the source of the note
* @param key
* the key of the note
* @param marker
* the marker to associate to the note
*
* @return a newly create note instance
*/
@SuppressWarnings("unchecked")
static Ref3 create(String source, String key, Marker marker) {
return (Ref3) new NoteImpl(source, key, marker);
}
}
/**
* Markers help to filter out note instances.
*/
sealed interface Marker permits NoteLevel {
/**
* Returns the name of this marker.
*
* @return the name of this marker
*/
String name();
}
/**
* The TRACE level is typically used for events that are for detailed internal
* workings.
*/
Marker TRACE = NoteLevel.TRACE;
/**
* The DEBUG level is typically used for events that are for debugging
* purposes.
*/
Marker DEBUG = NoteLevel.DEBUG;
/**
* The INFO level is typically used for events that are informational.
*/
Marker INFO = NoteLevel.INFO;
/**
* The WARN level is typically used for events demanding attention.
*/
Marker WARN = NoteLevel.WARN;
/**
* The ERROR level is typically used for events demanding immediate attention.
*/
Marker ERROR = NoteLevel.ERROR;
/**
* A no-op {@code Sink} implementation.
*/
static class NoOpSink implements Sink {
static final NoOpSink INSTANCE = new NoOpSink();
/**
* Sole constructor.
*/
protected NoOpSink() {}
public static NoOpSink create() {
return new NoOpSink();
}
/**
* Returns {@code false}.
*
* @param note
* a note instance (ignored)
*
* @return {@code false}
*/
@Override
public boolean isEnabled(Note note) {
return false;
}
/**
* Does nothing, this is a no-op sink.
*
* @param note
* a note instance (ignored)
* @param value
* a value (ignored)
*/
@Override
public void send(Int1 note, int value) {}
/**
* Does nothing, this is a no-op sink.
*
* @param note
* a note instance (ignored)
* @param value1
* a first value (ignored)
* @param value2
* a second value (ignored)
*/
@Override
public void send(Int2 note, int value1, int value2) {}
/**
* Does nothing, this is a no-op sink.
*
* @param note
* a note instance (ignored)
* @param value1
* a first value (ignored)
* @param value2
* a second value (ignored)
* @param value3
* a third value (ignored)
*/
@Override
public void send(Int3 note, int value1, int value2, int value3) {}
/**
* Does nothing, this is a no-op sink.
*
* @param note
* a note instance (ignored)
* @param value
* a value (ignored)
*/
@Override
public void send(Long1 note, long value) {}
/**
* Does nothing, this is a no-op sink.
*
* @param note
* a note instance (ignored)
* @param value1
* a first value (ignored)
* @param value2
* a second value (ignored)
*/
@Override
public void send(Long2 note, long value1, long value2) {}
/**
* Does nothing, this is a no-op sink.
*
* @param note
* a note instance (ignored)
*/
@Override
public void send(Ref0 note) {}
/**
* Does nothing, this is a no-op sink.
*
* @param note
* a note instance (ignored)
* @param value
* a value (ignored)
*/
@Override
public void send(Ref1 note, T1 value) {}
/**
* Does nothing, this is a no-op sink.
*
* @param note
* a note instance (ignored)
* @param value1
* a first value (ignored)
* @param value2
* a second value (ignored)
*/
@Override
public void send(Ref2 note, T1 value1, T2 value2) {}
/**
* Does nothing, this is a no-op sink.
*
* @param note
* a note instance (ignored)
* @param value1
* a first value (ignored)
* @param value2
* a second value (ignored)
* @param value3
* a third value (ignored)
*/
@Override
public void send(Ref3 note, T1 value1, T2 value2, T3 value3) {}
}
/**
* An object responsible for sending the notes of a program; it behaves as an
* event listener.
*/
interface Sink {
/**
* Returns {@code true} if the given {@code note} would be sent by this
* {@code NoteSink} instance.
*
* @param note
* the note to test
*
* @return {@code true} if the given {@code note} would be sent
*/
boolean isEnabled(Note note);
/**
* Sends the given note that takes a {@code int} argument.
*
* @param note
* an note instance
* @param value
* argument of the consumed note
*/
void send(Int1 note, int value);
/**
* Sends the given note that takes two {@code int} arguments.
*
* @param note
* an note instance
* @param value1
* first argument of the consumed note
* @param value2
* second argument of the consumed note
*/
void send(Int2 note, int value1, int value2);
/**
* Sends the given note that takes three {@code int} arguments.
*
* @param note
* an note instance
* @param value1
* first argument of the consumed note
* @param value2
* second argument of the consumed note
* @param value3
* third argument of the consumed note
*/
void send(Int3 note, int value1, int value2, int value3);
/**
* Sends the given note that takes a {@code long} argument.
*
* @param note
* an note instance
* @param value
* argument of the consumed note
*/
void send(Long1 note, long value);
/**
* Sends the given note that takes two {@code long} arguments.
*
* @param note
* an note instance
* @param value1
* first argument of the consumed note
* @param value2
* second argument of the consumed note
*/
void send(Long2 note, long value1, long value2);
/**
* Sends the given note that takes no arguments.
*
* @param note
* an note instance
*/
void send(Ref0 note);
/**
* Sends the given note that takes one object reference argument.
*
* @param type of the note argument
*
* @param note
* an note instance
*
* @param value
* argument of the consumed note (can be null)
*/
void send(Ref1 note, T1 value);
/**
* Sends the given note that takes two object reference arguments.
*
* @param type of the first note argument
* @param type of the second note argument
*
* @param note
* an note instance
* @param value1
* first argument of the consumed note (can be null)
* @param value2
* second argument of the consumed note (can be null)
*/
void send(Ref2 note, T1 value1, T2 value2);
/**
* Sends the given note that takes three object reference arguments.
*
* @param type of the first note argument
* @param type of the second note argument
* @param type of the third note argument
* @param note
* an note instance
* @param value1
* first argument of the consumed note (can be null)
* @param value2
* second argument of the consumed note (can be null)
* @param value3
* third argument of the consumed note (can be null)
*/
void send(Ref3 note, T1 value1, T2 value2, T3 value3);
}
/**
* Returns the source of this note. The source of an note is a name
* that indicates the origin of a note. The source is typically
* the fully qualified name of the class where the note is declared.
*
* @return the source of this note
*/
String source();
/**
* Returns the key of this note. The key of an note is a name that uniquely
* identifies an note within a given source.
*
* @return the key of this note
*/
String key();
/**
* Returns the first marker of this note.
*
* @return the first marker of this note
*/
Marker marker();
/**
* Returns {@code true} if this note has the specified marker.
*
* @param marker
* the marker
*
* @return {@code true} if this note has the specified marker
*/
default boolean has(Marker marker) {
return marker().equals(marker);
}
/**
* Returns {@code true} if this note has at least one of the specified
* markers.
*
* @param marker1
* the first marker
* @param marker2
* the second marker
*
* @return {@code true} if this note has at least one of the specified
* markers
*/
default boolean hasAny(Marker marker1, Marker marker2) {
return marker().equals(marker1)
|| marker().equals(marker2);
}
/**
* Returns {@code true} if this note has at least one of the specified
* markers.
*
* @param marker1
* the first marker
* @param marker2
* the second marker
* @param marker3
* the third marker
*
* @return {@code true} if this note has at least one of the specified
* markers
*/
default boolean hasAny(Marker marker1, Marker marker2, Marker marker3) {
return marker().equals(marker1)
|| marker().equals(marker2)
|| marker().equals(marker3);
}
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy