1/*
2 * Copyright (C) 2012 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
5 * use this file except in compliance with the License. You may obtain a copy of
6 * the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 * License for the specific language governing permissions and limitations under
14 * the License.
15 */
16
17package com.android.inputmethod.research;
18
19import com.android.inputmethod.latin.CollectionUtils;
20
21import java.util.LinkedList;
22
23/**
24 * A buffer that holds a fixed number of LogUnits.
25 *
26 * LogUnits are added in and shifted out in temporal order.  Only a subset of the LogUnits are
27 * actual words; the other LogUnits do not count toward the word limit.  Once the buffer reaches
28 * capacity, adding another LogUnit that is a word evicts the oldest LogUnits out one at a time to
29 * stay under the capacity limit.
30 */
31public class LogBuffer {
32    protected final LinkedList<LogUnit> mLogUnits;
33    /* package for test */ int mWordCapacity;
34    // The number of members of mLogUnits that are actual words.
35    protected int mNumActualWords;
36
37    /**
38     * Create a new LogBuffer that can hold a fixed number of LogUnits that are words (and
39     * unlimited number of non-word LogUnits), and that outputs its result to a researchLog.
40     *
41     * @param wordCapacity maximum number of words
42     */
43    LogBuffer(final int wordCapacity) {
44        if (wordCapacity <= 0) {
45            throw new IllegalArgumentException("wordCapacity must be 1 or greater.");
46        }
47        mLogUnits = CollectionUtils.newLinkedList();
48        mWordCapacity = wordCapacity;
49        mNumActualWords = 0;
50    }
51
52    /**
53     * Adds a new LogUnit to the front of the LIFO queue, evicting existing LogUnit's
54     * (oldest first) if word capacity is reached.
55     */
56    public void shiftIn(LogUnit newLogUnit) {
57        if (newLogUnit.getWord() == null) {
58            // This LogUnit isn't a word, so it doesn't count toward the word-limit.
59            mLogUnits.add(newLogUnit);
60            return;
61        }
62        if (mNumActualWords == mWordCapacity) {
63            shiftOutThroughFirstWord();
64        }
65        mLogUnits.add(newLogUnit);
66        mNumActualWords++; // Must be a word, or we wouldn't be here.
67    }
68
69    private void shiftOutThroughFirstWord() {
70        while (!mLogUnits.isEmpty()) {
71            final LogUnit logUnit = mLogUnits.removeFirst();
72            onShiftOut(logUnit);
73            if (logUnit.hasWord()) {
74                // Successfully shifted out a word-containing LogUnit and made space for the new
75                // LogUnit.
76                mNumActualWords--;
77                break;
78            }
79        }
80    }
81
82    /**
83     * Removes all LogUnits from the buffer without calling onShiftOut().
84     */
85    public void clear() {
86        mLogUnits.clear();
87        mNumActualWords = 0;
88    }
89
90    /**
91     * Called when a LogUnit is removed from the LogBuffer as a result of a shiftIn.  LogUnits are
92     * removed in the order entered.  This method is not called when shiftOut is called directly.
93     *
94     * Base class does nothing; subclasses may override.
95     */
96    protected void onShiftOut(LogUnit logUnit) {
97    }
98
99    /**
100     * Called to deliberately remove the oldest LogUnit.  Usually called when draining the
101     * LogBuffer.
102     */
103    public LogUnit shiftOut() {
104        if (mLogUnits.isEmpty()) {
105            return null;
106        }
107        final LogUnit logUnit = mLogUnits.removeFirst();
108        if (logUnit.hasWord()) {
109            mNumActualWords--;
110        }
111        return logUnit;
112    }
113}
114