jetbrains.exodus.io.Block Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of sonarlint-core Show documentation
Common library used by some SonarLint flavors
There is a newer version: 10.5.0.78949
/**
 * Copyright 2010 - 2022 JetBrains s.r.o.
 *
 * 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
 *
 * https://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 jetbrains.exodus.io;

import jetbrains.exodus.env.EnvironmentConfig;

/**
 * {@code Block} represents single {@code .xd} file in {@code Log} on storage device - disk, memory, network file
 * system. etc. {@code Block} is identified in the log by its {@linkplain #getAddress() address}. {@code Block}
 * has {@linkplain #length() length} in bytes, which is not greater than {@linkplain EnvironmentConfig#getLogFileSize()
 * maximum log block size}. {@code Block} implementation defines the way data is
 * {@linkplain #read(byte[], long, int, int) read} from storage device.
 *
 * {@code Log} blocks can be mutable and immutable. All blocks having length equal to {@linkplain EnvironmentConfig#getLogFileSize()
 * maximum log block size} are immutable. In any moment, only one block can be mutable. This has maximum {@linkplain
 * #getAddress() address}.
 *
 * @see DataReader
 * @see DataWriter
 * @see DataReaderWriterProvider
 * @see EnvironmentConfig#getLogFileSize()
 * @since 1.3.0
 */
public interface Block {

    /**
     * Returns address of the block in the {@code Log}. This address is always constant for the block.
     *
     * @return address of the block in the {@code Log}
     */
    long getAddress();

    /**
     * Returns length of the block in bytes. Block length is always not greater
     * than {@linkplain EnvironmentConfig#getLogFileSize() maximum log file size}.
     *
     * @return length of the block in bytes
     * @see EnvironmentConfig#getLogFileSize()
     */
    long length();

    /**
     * Reads data from the underlying store device.
     *
     * @param output   array to copy data
     * @param position starting position in the {@code .xd} file
     * @param offset   starting offset in the array
     * @param count    number of bytes to read
     * @return actual number of bytes read
     */
    int read(byte[] output, long position, int offset, int count);

    /**
     * For immutable {@code Block} implementations, this method returns fresh representation of the same {@code .xd}
     * file. For mutable {@code Block} implementations, this method just returns this {@code Block} instance.
     *
     * @return fresh representation of the same {@code .xd} file
     */
    Block refresh();
}