TimeBasedAlphanumericIdentifierGenerator.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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.
 */
/*
 * Modificato da Link.it (https://link.it) per supportare le seguenti funzionalità:
 * - Generazione ID all'interno delle interfacce di OpenSPCoop2
 * - Gestione caratteri massimi per numeri e cifre
 * - Possibilità di utilizzare lowerCase e/o upperCase
 * 
 * Copyright (c) 2005-2025 Link.it srl (https://link.it). 
 */
package org.openspcoop2.utils.id.apache.serial;

import java.io.Serializable;
import java.util.Arrays;
import java.util.Calendar;
import java.util.TimeZone;

import org.openspcoop2.utils.id.apache.AbstractStringIdentifierGenerator;


/**
 * <code>TimeBasedAlphanumericIdentifierGenerator</code> is an identifier generator that generates
 * an alphanumeric identifier in base 36 as a String object from the current UTC time and an
 * internal counter.
 * <p>
 * The generator guarantees that all generated ids have an increasing natural sort order (even if
 * the time internally has an overflow). The implementation additionally guarantees, that all
 * instances within the same process do generate unique ids. All generated ids have the same length
 * (padding with 0's on the left), which is determined by the maximum size of a long value and the
 * <code>postfixSize</code> parameter passed to the constructor.
 * </p>
 * <p>
 * Note: To ensure unique ids that are created within the same millisecond (or maximum time
 * resolution of the system), the implementation uses an internal counter. The maximum value of this
 * counter is determined by the <code>postfixSize</code> parameter i.e. the largest value that can
 * be represented in base 36. If the counter exceeds this value, an IllegalStateException is thrown.
 * </p>
 * <p>
 * Note: The uniqueness of the generated ids cannot be guaranteed if the system performs time shifts
 * of more than a second, that affect the running processes.
 * </p>.
 *
 * Author of the original commons apache code:
 * @author Commons-Id team
 * @version $Id$
 *
 * Authors of the Link.it modification to the code:
 * @author $Author$
 * @version $Rev$, $Date$
 */
public class TimeBasedAlphanumericIdentifierGenerator extends AbstractStringIdentifierGenerator
        implements Serializable {

    /**
     * <code>serialVersionUID</code> is the serializable UID for the binary version of the class.
     */
    private static final long serialVersionUID = 20060116L;
    /**
     * <code>padding</code> an array of '0' for improved padding performance.
     */
    private static final char[] padding;
    static {
        padding = new char[MAX_LONG_ALPHANUMERIC_VALUE_LENGTH];
        Arrays.fill(padding, '0');
    }
    /**
     * <code>UTC</code> is the UTC {@link TimeZone} instance.
     */
    private static final TimeZone UTC = TimeZone.getTimeZone("UTC");
    /**
     * <code>last</code> is the marker, when the counter was resetted the last time.
     */
    private static long last = 0;
    /**
     * <code>counter</code> counts the number of generated identifiers since the last reset.
     */
    private static long counter = 0;
    /**
     * <code>postfixSize</code> size of the postfix, that contains the padded counter in base 36.
     */
    private final int postfixSize;
    private final long offset;
    
    /**
     * Construct a TimeBasedAlphanumericIdentifierGenerator with a defined size of the postfix and
     * an offset for the time value. The offset can be used to manipulate the representation of the
     * time value in the generated id. If a TimeBasedAlphanumericIdentifierGenerator is constructed
     * with an offset of the current number of milliseconds since 1st Jan 1970 the first generated
     * id in the same millisecond will have an id consisting of a sequence of '0' characters.
     * 
     * @param postfixSize the size of the postfix
     * @param offset the offset taken into account for the time value
     * @throws IllegalArgumentException if <code>postfixSize</code> is negative or exceeds the
     *             maximum size for representing {@link Long#MAX_VALUE} in base 36
     */
    public TimeBasedAlphanumericIdentifierGenerator(final int postfixSize, final long offset) {
        if (postfixSize < 0 || postfixSize > MAX_LONG_ALPHANUMERIC_VALUE_LENGTH) {
            throw new IllegalArgumentException("Invalid size for postfix");
        }
        this.postfixSize = postfixSize;
        this.offset = offset;
    }

    /**
     * Construct a TimeBasedAlphanumericIdentifierGenerator with a defined size of the postfix.
     * 
     * @param postfixSize the size of the postfix defining the maximum number of possible ids
     *            generated within the same millisecond (depending on the time resolution of the
     *            running system)
     * @throws IllegalArgumentException if <code>postfixSize</code> is negative or exceeds the
     *             maximum size for representing {@link Long#MAX_VALUE} in base 36
     */
    public TimeBasedAlphanumericIdentifierGenerator(final int postfixSize) {
        this(postfixSize, 0);
    }

    /**
     * Construct a TimeBasedAlphanumericIdentifierGenerator with a default size of the postfix of 3.
     */
    public TimeBasedAlphanumericIdentifierGenerator() {
        this(3);
    }

    @Override
    public long maxLength() {
        return ((long)MAX_LONG_ALPHANUMERIC_VALUE_LENGTH) + ((long)this.postfixSize);
    }

    @Override
    public long minLength() {
        return maxLength();
    }

    private static void updateLast(long now) {
        last = now;
    }
    private static void resetCounter() {
        counter = 0;
    }
    private static void incrementCounter() {
        ++counter;
    }
    
    @Override
    public String nextStringIdentifier() throws MaxReachedException {
        long now;
        synchronized (this) {
            now = Calendar.getInstance(UTC).getTime().getTime(); // JDK 1.3 compatibility
            final long diff = now - last;
            // external time correction of more than a second or overflow
            if (diff > 0 || diff < -1000) {
                updateLast(now);
                resetCounter();
            } else {
                if (diff != 0) {
                    now = last; // ignore time shift
                }
                incrementCounter();
            }
        }
        final String postfix = counter > 0
                                          ? Long.toString(counter, ALPHA_NUMERIC_CHARSET_SIZE) : "";
        if (postfix.length() > this.postfixSize) {
            throw new MaxReachedException(
                    "The maximum number of identifiers in this millisecond has been reached");
        }
        // ensure, that no negative value is used and values stay increasing
        long base = now - this.offset;
        long value = base < 0 ? base + Long.MAX_VALUE + 1 : base;
        final String time = Long.toString(value, ALPHA_NUMERIC_CHARSET_SIZE);
        final char[] buffer = new char[MAX_LONG_ALPHANUMERIC_VALUE_LENGTH + this.postfixSize];
        int i = 0;
        int maxPad = MAX_LONG_ALPHANUMERIC_VALUE_LENGTH - time.length();
        if (maxPad > 0) {
            System.arraycopy(padding, 0, buffer, 0, maxPad);
        }
        System.arraycopy(time.toCharArray(), 0, buffer, maxPad, time.length());
        if (base < 0) {
            // Representation of Long.MAX_VALUE starts with '1', negative 'base' means higher value
            // in time
            buffer[0] += 2;
        }
        i += time.length() + maxPad;
        if (this.postfixSize > 0) {
            maxPad = this.postfixSize - postfix.length();
            if (maxPad > 0) {
                System.arraycopy(padding, 0, buffer, i, maxPad);
                i += maxPad;
            }
            System.arraycopy(postfix.toCharArray(), 0, buffer, i, postfix.length());
        }
        return new String(buffer);
    }

    /**
     * Retrieve the number of milliseconds since 1st Jan 1970 that were the base for the given id.
     * 
     * @param id the id to use
     * @param offset the offset used to create the id
     * @return the number of milliseconds
     * @throws IllegalArgumentException if <code>id</code> is not a valid id from this type of
     *             generator
     */
    public long getMillisecondsFromId(final Object id, final long offset) {
        if (id instanceof String && id.toString().length() >= MAX_LONG_ALPHANUMERIC_VALUE_LENGTH) {
            final char[] buffer = new char[MAX_LONG_ALPHANUMERIC_VALUE_LENGTH];
            System.arraycopy(
                    id.toString().toCharArray(), 0, buffer, 0, MAX_LONG_ALPHANUMERIC_VALUE_LENGTH);
            final boolean overflow = buffer[0] > '1';
            if (overflow) {
                buffer[0] -= 2;
            }
            long value = Long.parseLong(new String(buffer), ALPHA_NUMERIC_CHARSET_SIZE);
            if (overflow) {
                value -= Long.MAX_VALUE + 1;
            }
            return value + offset;
        }
        throw new IllegalArgumentException("'" + id + "' is not an id from this generator");
    }
}