1/*
2 * Copyright (c) 1997, 2001, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.  Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26package sun.rmi.log;
27
28import java.io.*;
29import sun.rmi.server.MarshalOutputStream;
30import sun.rmi.server.MarshalInputStream;
31
32/**
33 * A LogHandler represents snapshots and update records as serializable
34 * objects.
35 *
36 * This implementation does not know how to create an initial snaphot or
37 * apply an update to a snapshot.  The client must specifiy these methods
38 * via a subclass.
39 *
40 * @see ReliableLog
41 *
42 * @author Ann Wollrath
43 */
44public abstract
45class LogHandler {
46
47    /**
48     * Creates a LogHandler for a ReliableLog.
49     */
50    public LogHandler() {}
51
52    /**
53     * Creates and returns the initial state of data structure that needs
54     * to be stably stored. This method is called when a ReliableLog is
55     * created.
56     * @return the initial state
57     * @exception Exception can raise any exception
58     */
59    public abstract
60    Object initialSnapshot() throws Exception;
61
62    /**
63     * Writes the snapshot object to a stream.  This callback is
64     * invoked when the client calls the snaphot method of ReliableLog.
65     * @param out the output stream
66     * @param value the snapshot
67     * @exception Exception can raise any exception
68     */
69    public
70    void snapshot(OutputStream out, Object value) throws Exception {
71        MarshalOutputStream s = new MarshalOutputStream(out);
72        s.writeObject(value);
73        s.flush();
74    }
75
76    /**
77     * Read the snapshot object from a stream and returns the snapshot.
78     * This callback is invoked when the client calls the recover method
79     * of ReliableLog.
80     * @param in the input stream
81     * @return the state (snapshot)
82     * @exception Exception can raise any exception
83     */
84
85    public
86    Object recover(InputStream in) throws Exception {
87        MarshalInputStream s = new MarshalInputStream(in);
88        return s.readObject();
89    }
90
91    /**
92     * Writes the representation (a serializable object) of an update
93     * to a stream.  This callback is invoked when the client calls the
94     * update method of ReliableLog.
95     * @param out the output stream
96     * @param value the snapshot
97     * @exception Exception can raise any exception
98     */
99    public
100    void writeUpdate(LogOutputStream out, Object value) throws Exception {
101
102        MarshalOutputStream s = new MarshalOutputStream(out);
103        s.writeObject(value);
104        s.flush();
105    }
106
107    /**
108     * Reads a stably logged update (a serializable object) from a
109     * stream.  This callback is invoked during recovery, once for
110     * every record in the log.  After reading the update, this method
111     * invokes the applyUpdate (abstract) method in order to obtain
112     * the new snapshot value.  It then returns the new snapshot.
113     *
114     * @param in the input stream
115     * @param state the current state
116     * @return the new state
117     * @exception Exception can raise any exception
118     */
119    public
120    Object readUpdate(LogInputStream in, Object state) throws Exception {
121        MarshalInputStream  s = new MarshalInputStream(in);
122        return applyUpdate(s.readObject(), state);
123    }
124
125    /**
126     * Reads a stably logged update (a serializable object) from a stream.
127     * This callback is invoked during recovery, once for every record in the
128     * log.  After reading the update, this method is invoked in order to
129     * obtain the new snapshot value.  The method should apply the update
130     * object to the current state <code>state</code> and return the new
131     * state (the new snapshot value).
132     * @param update the update object
133     * @param state the current state
134     * @return the new state
135     * @exception Exception can raise any exception
136     */
137    public abstract
138    Object applyUpdate(Object update, Object state) throws Exception;
139
140}
141