<commit_before>/*******************************************************************************
 * Copyright (c) 2010 Oak Ridge National Laboratory.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 ******************************************************************************/
package org.csstudio.archive.reader;

import org.csstudio.data.values.ITimestamp;

/** Interface to archive data retrieval.
 *  <p>
 *  To get an actual implementation, use the ArchiveRepository.
 *  <p>
 *  Note that most methods in this API naturally require a network request
 *  or a lengthy search for data, so they will possibly take some time to
 *  complete.
 *  <p>
 *  Historic remark:
 *  Much of this code is based on the java archive viewer's
 *  data library, primarily written by <NAME> and <NAME>,
 *  with contributions by <NAME>, all at LANL at the time.
 *  The first CSS implementation was in org.csstudio.archive.
 *  <p>
 *  The difference between this archive reader API and the previous CSS
 *  org.csstudio.archive implementation:
 *  <ul>
 *  <li>Samples are fetched via iterators, similar to JDBC.
 *      The old API returned an array of samples and would either run out of
 *      memory when trying to get a lot of data, or return only a fraction of
 *      the requested data, which in turn required another layer of code to
 *      iterate over 'batches' of partial results.
 *      This iterator-based API can be used to export virtually unlimited
 *      amounts of data, sample by sample, for computations or export
 *      to other data formats. It is up to the implementation to optimize
 *      the data transfer, for example like JDBC's internal fetch size.
 *  <li>Functionality that several data providers never actually implemented
 *      has been removed (start/end time of a channel's sample range)
 *  <li>Channel search via 'glob' pattern, which can be a lot faster than
 *      regular expression search, is directly supported.
 *  </ul>
 *
 *  @see ArchiveRepository
 *
 *  @author <NAME>
 *  @author <NAME>, <NAME>, <NAME>:
 *          Contributed to org.csstudio.archive
 *  @author <NAME>, <NAME>, <NAME>:
 *          Created original Java archive viewer
 */
public interface ArchiveReader
{
    /** Server name information.
     *  <p>
     *  Unique name of this ArchiveServer implementation.
     *  <p>
     *  The Description, Version and URL give more detail.
     *  This string is meant for tools that need a short
     *  description of the data source, for example
     *  "Channel Archiver" or "Archive Record" etc.
     *  @return Name of the server.
     */
    public String getServerName();

    /** URL for this ArchiveServer.
     *  @return URL as a string.
     */
    public String getURL();

    /** Arbitrary description string, may span multiple lines,
     *  with details left to the implementation.
     *  @return Description string.
     */
    public String getDescription();

    /** Version information.
     *  <p>
     *  The meaning of this version number is up to the implementation.
     *  @return A version number.
     */
    public int getVersion();

    /** Obtain a list of archives handled by this server.
     *  <p>
     *  A server might support access to more than one sub-archive.
     *
     *  @return The available archives, at least one.
     */
    public ArchiveInfo[] getArchiveInfos();

    /** Find channel in given sub-archive via "file glob" pattern search.
     *  <p>
     *  In principle, globs can be translated into regular expressions,
     *  then use <code>getNamesByRegExp()</code>. But file globs
     *  can be a lot faster for some implementations, and are also known
     *  by more users, so a designated call appeared appropriate.
     *  <p>
     *  The search should be case-insensitive, but details can depend
     *  on the implementation.
     *
     *  @param key Key of archive to search.
     *  @param glob_pattern Pattern for channel name with '*' or '?'.
     *  @return List of matching channel names. Might be empty.
     *  @throws Exception on wrong key or internal error.
     */
    public String[] getNamesByPattern(int key, String glob_pattern)
        throws Exception;

    /** Find channel in given sub-archive via regular expression search.
     *  <p>
     *  The search should be case-insensitive, but details can depend
     *  on the implementation.
     *
     *  @param key Key of archive to search.
     *  @param reg_exp Regular Expression for channel name.
     *  @return List of matching channel names. Might be empty.
     *  @throws Exception on wrong key or internal error.
     */
    public String[] getNamesByRegExp(int key, String reg_exp)
        throws Exception;

    /** Read original, raw samples from the archive
     *  @param key Key of the archive to use for retrieval.
     *  @param name Channel name
     *  @param start Start time
     *  @param end End time
     *  @return ValueIterator for the 'raw' samples in the archive<commit_msg>archive.reader: API comment on handling empty channel name pattern<commit_after>/*******************************************************************************
 * Copyright (c) 2010 Oak Ridge National Laboratory.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 ******************************************************************************/
package org.csstudio.archive.reader;

import org.csstudio.data.values.ITimestamp;

/** Interface to archive data retrieval.
 *  <p>
 *  To get an actual implementation, use the ArchiveRepository.
 *  <p>
 *  Note that most methods in this API naturally require a network request
 *  or a lengthy search for data, so they will possibly take some time to
 *  complete.
 *  <p>
 *  Historic remark:
 *  Much of this code is based on the java archive viewer's
 *  data library, primarily written by <NAME> and <NAME>sov,
 *  with contributions by <NAME>, all at LANL at the time.
 *  The first CSS implementation was in org.csstudio.archive.
 *  <p>
 *  The difference between this archive reader API and the previous CSS
 *  org.csstudio.archive implementation:
 *  <ul>
 *  <li>Samples are fetched via iterators, similar to JDBC.
 *      The old API returned an array of samples and would either run out of
 *      memory when trying to get a lot of data, or return only a fraction of
 *      the requested data, which in turn required another layer of code to
 *      iterate over 'batches' of partial results.
 *      This iterator-based API can be used to export virtually unlimited
 *      amounts of data, sample by sample, for computations or export
 *      to other data formats. It is up to the implementation to optimize
 *      the data transfer, for example like JDBC's internal fetch size.
 *  <li>Functionality that several data providers never actually implemented
 *      has been removed (start/end time of a channel's sample range)
 *  <li>Channel search via 'glob' pattern, which can be a lot faster than
 *      regular expression search, is directly supported.
 *  </ul>
 *
 *  @see ArchiveRepository
 *
 *  @author <NAME>
 *  @author <NAME>, <NAME>, <NAME>:
 *          Contributed to org.csstudio.archive
 *  @author <NAME>, <NAME>, <NAME>:
 *          Created original Java archive viewer
 */
public interface ArchiveReader
{
    /** Server name information.
     *  <p>
     *  Unique name of this ArchiveServer implementation.
     *  <p>
     *  The Description, Version and URL give more detail.
     *  This string is meant for tools that need a short
     *  description of the data source, for example
     *  "Channel Archiver" or "Archive Record" etc.
     *  @return Name of the server.
     */
    public String getServerName();

    /** URL for this ArchiveServer.
     *  @return URL as a string.
     */
    public String getURL();

    /** Arbitrary description string, may span multiple lines,
     *  with details left to the implementation.
     *  @return Description string.
     */
    public String getDescription();

    /** Version information.
     *  <p>
     *  The meaning of this version number is up to the implementation.
     *  @return A version number.
     */
    public int getVersion();

    /** Obtain a list of archives handled by this server.
     *  <p>
     *  A server might support access to more than one sub-archive.
     *
     *  @return The available archives, at least one.
     */
    public ArchiveInfo[] getArchiveInfos();

    /** Find channel in given sub-archive via "file glob" pattern search.
     *  <p>
     *  In principle, globs can be translated into regular expressions,
     *  then use <code>getNamesByRegExp()</code>. But file globs
     *  can be a lot faster for some implementations, and are also known
     *  by more users, so a designated call appeared appropriate.
     *  <p>
     *  The search should be case-insensitive, but details can depend
     *  on the implementation.
     *  <p>
     *  It is not fully defined how to handle an empty pattern.
     *  Ideally, the result would be empty.
     *  To locate <u>all</u> channels in the archive, the user
     *  needs to specifically search for "*".
     *  But some existing implementations return all channels
     *  for an empty pattern...
     *
     *  @param key Key of archive to search.
     *  @param glob_pattern Pattern for channel name with '*' or '?'.
     *  @return List of matching channel names. Might be empty.
     *  @throws Exception on wrong key or internal error.
     */
    public String[] getNamesByPattern(int key, String glob_pattern)
        throws Exception;

    /** Find channel in given sub-archive via regular expression search.
     *  <p>
     *  For case-sensitivity and handling of empty regular expression refer to
     *  <code>getNamesByPattern</code>
     *
     *  @param key Key of archive to search.
     *  @param reg_exp Regular Expression for channel name.
     *  @return List of matching channel names. Might be empty.
     *  @throws Exception on wrong key or internal error.
     */
    public String[] getNamesByRegExp(int key, String reg_exp)
        throws Exception;

    /** Read original, raw samples from the archive
     *  @param key Key of the archive to use for retrieval.
     *  @param name Channel name
     *  @param start Start time
     *  @param end End time
     *  @return ValueIterator for the 'raw' samples in the archive
{'fraction_non_alphanumeric': 0.10276386570209609, 'fraction_numerical': 0.0014839547393804488, 'mean_word_length': 2.8524473026080743, 'pattern_counts': {'":': 0, '<': 64, '<?xml version=': 0, '>': 64, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3962186', 'n_tokens_mistral': 2866, 'n_tokens_neox': 2760, 'n_words': 1301}