br.com.objectos.logging.Event Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of objectos-logging Show documentation
The Objectos Logging API. This is the API only, an implementation is needed during runtime.
There is a newer version: 3.1.0
/*
 * Copyright (C) 2021-2022 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 br.com.objectos.logging;

import br.com.objectos.core.object.Checks;
import br.com.objectos.core.object.Equals;
import br.com.objectos.core.object.HashCode;

/**
 * Represents an event of a program execution that can be logged. Examples of
 * events that can be modeled by instances of this class are
 *
 * 
 * the application start;
 * the operation to be performed by a class completes abruptly because of
 * exception {@code e}; and
 * the service implemented by a class receives a message with values
 * {@code x} and {@code y}.
 * 
 *
 * 
 * This class represents the event specification, not the event instance; a
 * logging message is an invocation of instances of this class. From this, a
 * logging message is (logically) composed of a logging event (instances of this
 * class) and zero or more arguments.
 *
 * 

 * As an example, suppose that you want to log the successful GET responses of a
 * HTTP server. The log message should contain the client's IP address, the path
 * name of the resource and the total number of bytes sents. The following could
 * be the event specification
 *
 * 
 * {@code Event3 GET_OK = Events.info(
 *     HttpServer.class, "HTTP_GET_OK", InetAddress.class, String.class, Integer.class
 * );}
 *
 * 
 * While the invocation of this event, i.e., the actual log message would be
 * in the form
 *
 * 
 * logger.log(GET_OK, clientAddress, pathName, bytes.length);
 *
 * Therefore, an {@code Event} instance indicates:
 *
 * 
 * the {@code source} of a log message. The {@code source} is the class
 * from which a log message originated;
 * the {@code level} of a log message;
 * the {@code key} of the event. The event key is a name that uniquely
 * identifies the event within a {@code source}. It also serves as a description
 * of the event itself; and
 * the number and the types of the arguments that should be supplied to a
 * {@link Logger} instance when invoking this event.
 * 
 *
 * @since 2
 */
public abstract class Event {

  private final String key;

  private final Level level;

  private final Class source;

  Event(Class source, String key, Level level) {
    this.key = Checks.checkNotNull(key, "key == null");

    this.level = Checks.checkNotNull(level, "level == null");

    this.source = Checks.checkNotNull(source, "source == null");
  }

  /**
   * 
   * Compares the specified object with this event for equality. Returns
   * {@code true} if and only if
   *
   * 

   * the specified object is also a {@code Event};
   * the specified object is of the same subclass of {@code Event};
   * both events have keys that are equal to each other; and
   * both events have source classes that are equal to each other.
   * 
   *
   * @param obj
   *        the object to be compared for equality with this event
   *
   * @return {@code true} if the specified object is equal to this event
   */
  @Override
  public final boolean equals(Object obj) {
    return obj == this || obj instanceof Event && equals0((Event) obj);
  }

  /**
   * Returns the key of this event.
   *
   * @return the key of this event
   */
  public final String getKey() {
    return key;
  }

  /**
   * Returns the logging level of this event.
   *
   * @return the logging level of this event
   */
  public final Level getLevel() {
    return level;
  }

  /**
   * Returns the source class of this event.
   *
   * @return the source class of this event
   */
  public final Class getSource() {
    return source;
  }

  /**
   * Returns the hash code value of this event.
   *
   * @return the hash code value of this event
   */
  @Override
  public final int hashCode() {
    return HashCode.hashCode(key, source);
  }

  /**
   * Returns {@code true} if this event would be logged at the specified
   * {@code level}.
   *
   * @param level
   *        the level to check against
   *
   * @return {@code true} if this event would be logged at the specified
   *         {@code level}
   */
  public final boolean isEnabled(Level level) {
    return this.level.compareTo(level) >= 0;
  }

  /**
   * Returns a string representation of this event.
   *
   * @return a string representation of this event
   */
  @Override
  public final String toString() {
    StringBuilder sb = new StringBuilder();

    Class type;
    type = getClass();

    sb.append(type.getSimpleName());

    sb.append('[');

    sb.append(source.getCanonicalName());

    sb.append(',');

    sb.append(level.name());

    sb.append(',');

    sb.append(key);

    sb.append(']');

    return sb.toString();
  }

  private boolean equals0(Event that) {
    return Equals.objects(
        getClass(), that.getClass(),
        key, that.key,
        source, that.source
    );
  }

}