[deliverable/tracecompass.git] / org.eclipse.linuxtools.tmf.core / src / org / eclipse / linuxtools / tmf / core / statesystem / helpers / IStateSystemBuilder.java

/*******************************************************************************
 * Copyright (c) 2012 Ericsson
 *
 * 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
 *
 * Contributors:
 *   Alexandre Montplaisir - Initial API
 ******************************************************************************/

package org.eclipse.linuxtools.tmf.core.statesystem.helpers;

import org.eclipse.linuxtools.tmf.core.statesystem.AttributeNotFoundException;
import org.eclipse.linuxtools.tmf.core.statesystem.TimeRangeException;
import org.eclipse.linuxtools.tmf.core.statevalue.ITmfStateValue;
import org.eclipse.linuxtools.tmf.core.statevalue.StateValueTypeException;

/**
 * This is the external interface to build or modify an existing state history.
 * 
 * It extends IStateSystemEnquirer, so you can still use it for reading the
 * history, but it also provides write-access to it with the quark-creating and
 * state-change insertion methods.
 * 
 * @author alexmont
 * 
 */
public interface IStateSystemBuilder extends IStateSystemQuerier {

    /**
     * @name Read/write quark-getting methods
     */

    /**
     * Basic quark-retrieving method. Pass an attribute in parameter as an array
     * of strings, the matching quark will be returned.
     * 
     * This version WILL create new attributes: if the attribute passed in
     * parameter is new in the system, it will be added and its new quark will
     * be returned.
     * 
     * @param attribute
     *            Attribute given as its full path in the Attribute Tree
     * @return The quark of the attribute (which either existed or just got
     *         created)
     */
    public int getQuarkAbsoluteAndAdd(String... attribute);

    /**
     * "Relative path" quark-getting method. Instead of specifying a full path,
     * if you know the path is relative to another attribute for which you
     * already have the quark, use this for better performance.
     * 
     * This is useful for cases where a lot of modifications or queries will
     * originate from the same branch of the attribute tree : the common part of
     * the path won't have to be re-hashed for every access.
     * 
     * This version WILL create new attributes: if the attribute passed in
     * parameter is new in the system, it will be added and its new quark will
     * be returned.
     * 
     * @param startingNodeQuark
     *            The quark of the attribute from which 'subPath' originates.
     * @param subPath
     *            "Rest" of the path to get to the final attribute
     * @return The matching quark, either if it's new of just got created.
     */
    public int getQuarkRelativeAndAdd(int startingNodeQuark, String... subPath);

    /**
     * @name State-changing methods
     */

    /**
     * Modify a current "ongoing" state (instead of inserting a state change,
     * like modifyAttribute() and others).
     * 
     * This can be used to update the value of a previous state change, for
     * example when we get information at the end of the state and not at the
     * beginning. (return values of system calls, etc.)
     * 
     * Note that past states can only be modified while they are still in
     * memory, so only the "current state" can be updated. Once they get
     * committed to disk (by inserting a new state change) it becomes too late.
     * 
     * @param newValue
     *            The new value that will overwrite the "current" one.
     * @param attributeQuark
     *            For which attribute in the system
     * @throws AttributeNotFoundException
     *             If the requested attribute is invalid
     */
    public void updateOngoingState(ITmfStateValue newValue, int attributeQuark)
            throws AttributeNotFoundException;

    /**
     * Basic attribute modification method, we simply specify a new value, for a
     * given attribute, effective at the given timestamp.
     * 
     * @param t
     *            Timestamp of the state change
     * @param value
     *            The State Value we want to assign to the attribute
     * @param attributeQuark
     *            Integer value of the quark corresponding to the attribute we
     *            want to modify
     * @throws TimeRangeException
     *             If the requested time is outside of the trace's range
     * @throws AttributeNotFoundException
     *             If the requested attribute quark is invalid
     * @throws StateValueTypeException
     *             If the inserted state value's type does not match what is
     *             already assigned to this attribute.
     */
    public void modifyAttribute(long t, ITmfStateValue value, int attributeQuark)
            throws TimeRangeException, AttributeNotFoundException,
            StateValueTypeException;

    /**
     * Increment attribute method. Reads the current value of a given integer
     * attribute (this value is right now in the Transient State), and increment
     * it by 1. Useful for statistics.
     * 
     * @param t
     *            Timestamp of the state change
     * @param attributeQuark
     *            Attribute to increment. If it doesn't exist it will be added,
     *            with a new value of 1.
     * @throws StateValueTypeException
     *             If the attribute already exists but is not of type Integer
     * @throws TimeRangeException
     *             If the given timestamp is invalid
     * @throws AttributeNotFoundException
     *             If the quark is invalid
     */
    public void incrementAttribute(long t, int attributeQuark)
            throws StateValueTypeException, TimeRangeException,
            AttributeNotFoundException;

    /**
     * "Push" helper method. This uses the given integer attribute as a stack:
     * The value of that attribute will represent the stack depth (always >= 1).
     * Sub-attributes will be created, their base-name will be the position in
     * the stack (1, 2, etc.) and their value will be the state value 'value'
     * that was pushed to this position.
     * 
     * @param t
     *            Timestamp of the state change
     * @param value
     *            State value to assign to this stack position.
     * @param attributeQuark
     *            The base attribute to use as a stack. If it does not exist if
     *            will be created (with depth = 1)
     * @throws TimeRangeException
     *             If the requested timestamp is invalid
     * @throws AttributeNotFoundException
     *             If the attribute is invalid
     * @throws StateValueTypeException
     *             If the attribute 'attributeQuark' already exists, but is not
     *             of integer type.
     */
    public void pushAttribute(long t, ITmfStateValue value, int attributeQuark)
            throws TimeRangeException, AttributeNotFoundException,
            StateValueTypeException;

    /**
     * Antagonist of the pushAttribute(), pops the top-most attribute on the
     * stack-attribute. If this brings it back to depth = 0, the attribute is
     * kept with depth = 0. If the value is already 0, or if the attribute
     * doesn't exist, nothing is done.
     * 
     * @param t
     *            Timestamp of the state change
     * @param attributeQuark
     *            Quark of the stack-attribute to pop
     * @throws AttributeNotFoundException
     *             If the attribute is invalid
     * @throws TimeRangeException
     *             If the timestamp is invalid
     * @throws StateValueTypeException
     *             If the target attribute already exists, but its state value
     *             type is invalid (not an integer)
     */
    public void popAttribute(long t, int attributeQuark)
            throws AttributeNotFoundException, TimeRangeException,
            StateValueTypeException;

    /**
     * Remove attribute method. Similar to the above modify- methods, with value
     * = 0 / null, except we will also "nullify" all the sub-contents of the
     * requested path (a bit like "rm -rf")
     * 
     * @param t
     *            Timestamp of the state change
     * @param attributeQuark
     *            Attribute to remove
     * @throws TimeRangeException
     *             If the timestamp is invalid
     * @throws AttributeNotFoundException
     *             If the quark is invalid
     */
    public void removeAttribute(long t, int attributeQuark)
            throws TimeRangeException, AttributeNotFoundException;

    /**
     * Method to close off the History Provider. This happens for example when
     * we are done reading an off-line trace. First we close the TransientState,
     * commit it to the Provider, mark it as inactive, then we write the
     * Attribute Tree somewhere so we can reopen it later.
     * 
     * @param endTime
     *            The requested End Time of the history, since it could be
     *            bigger than the timestamp of the last event or state change we
     *            have seen. All "ongoing" states will be extended until this
     *            'endTime'.
     * @throws TimeRangeException
     *             If the passed endTime doesn't make sense (for example, if
     *             it's earlier than the latest time) and the backend doesn't
     *             know how to handle it.
     */
    public void closeHistory(long endTime) throws TimeRangeException;
}
Commit	Line	Data
d26f90fd AM	1	/*******************************************************************************
	2	* Copyright (c) 2012 Ericsson
	3	*
	4	* All rights reserved. This program and the accompanying materials are
	5	* made available under the terms of the Eclipse Public License v1.0 which
	6	* accompanies this distribution, and is available at
	7	* http://www.eclipse.org/legal/epl-v10.html
	8	*
	9	* Contributors:
	10	* Alexandre Montplaisir - Initial API
	11	******************************************************************************/
	12
	13	package org.eclipse.linuxtools.tmf.core.statesystem.helpers;
	14
	15	import org.eclipse.linuxtools.tmf.core.statesystem.AttributeNotFoundException;
	16	import org.eclipse.linuxtools.tmf.core.statesystem.TimeRangeException;
	17	import org.eclipse.linuxtools.tmf.core.statevalue.ITmfStateValue;
	18	import org.eclipse.linuxtools.tmf.core.statevalue.StateValueTypeException;
	19
	20	/**
	21	* This is the external interface to build or modify an existing state history.
	22	*
	23	* It extends IStateSystemEnquirer, so you can still use it for reading the
	24	* history, but it also provides write-access to it with the quark-creating and
	25	* state-change insertion methods.
	26	*
	27	* @author alexmont
	28	*
	29	*/
	30	public interface IStateSystemBuilder extends IStateSystemQuerier {
	31
	32	/**
	33	* @name Read/write quark-getting methods
	34	*/
	35
	36	/**
	37	* Basic quark-retrieving method. Pass an attribute in parameter as an array
	38	* of strings, the matching quark will be returned.
	39	*
	40	* This version WILL create new attributes: if the attribute passed in
	41	* parameter is new in the system, it will be added and its new quark will
	42	* be returned.
	43	*
	44	* @param attribute
	45	* Attribute given as its full path in the Attribute Tree
	46	* @return The quark of the attribute (which either existed or just got
	47	* created)
	48	*/
	49	public int getQuarkAbsoluteAndAdd(String... attribute);
	50
	51	/**
	52	* "Relative path" quark-getting method. Instead of specifying a full path,
	53	* if you know the path is relative to another attribute for which you
	54	* already have the quark, use this for better performance.
	55	*
	56	* This is useful for cases where a lot of modifications or queries will
	57	* originate from the same branch of the attribute tree : the common part of
	58	* the path won't have to be re-hashed for every access.
	59	*
	60	* This version WILL create new attributes: if the attribute passed in
	61	* parameter is new in the system, it will be added and its new quark will
	62	* be returned.
	63	*
	64	* @param startingNodeQuark
65	* The quark of the attribute from which 'subPath' originates.
66	* @param subPath
67	* "Rest" of the path to get to the final attribute
68	* @return The matching quark, either if it's new of just got created.
69	*/
70	public int getQuarkRelativeAndAdd(int startingNodeQuark, String... subPath);
71
72	/**
73	* @name State-changing methods
74	*/
75
76	/**
77	* Modify a current "ongoing" state (instead of inserting a state change,
78	* like modifyAttribute() and others).
79	*
80	* This can be used to update the value of a previous state change, for
81	* example when we get information at the end of the state and not at the
82	* beginning. (return values of system calls, etc.)
83	*
84	* Note that past states can only be modified while they are still in
85	* memory, so only the "current state" can be updated. Once they get
86	* committed to disk (by inserting a new state change) it becomes too late.
87	*
88	* @param newValue
89	* The new value that will overwrite the "current" one.
90	* @param attributeQuark
91	* For which attribute in the system
92	* @throws AttributeNotFoundException
93	* If the requested attribute is invalid
94	*/
95	public void updateOngoingState(ITmfStateValue newValue, int attributeQuark)
96	throws AttributeNotFoundException;
97
98	/**
99	* Basic attribute modification method, we simply specify a new value, for a
100	* given attribute, effective at the given timestamp.
101	*
102	* @param t
103	* Timestamp of the state change
104	* @param value
105	* The State Value we want to assign to the attribute
106	* @param attributeQuark
107	* Integer value of the quark corresponding to the attribute we
108	* want to modify
109	* @throws TimeRangeException
110	* If the requested time is outside of the trace's range
111	* @throws AttributeNotFoundException
112	* If the requested attribute quark is invalid
113	* @throws StateValueTypeException
114	* If the inserted state value's type does not match what is
115	* already assigned to this attribute.
116	*/
117	public void modifyAttribute(long t, ITmfStateValue value, int attributeQuark)
118	throws TimeRangeException, AttributeNotFoundException,
119	StateValueTypeException;
120
121	/**
122	* Increment attribute method. Reads the current value of a given integer
123	* attribute (this value is right now in the Transient State), and increment
124	* it by 1. Useful for statistics.
125	*
126	* @param t
127	* Timestamp of the state change
128	* @param attributeQuark
129	* Attribute to increment. If it doesn't exist it will be added,
130	* with a new value of 1.
131	* @throws StateValueTypeException
132	* If the attribute already exists but is not of type Integer
133	* @throws TimeRangeException
134	* If the given timestamp is invalid
135	* @throws AttributeNotFoundException
136	* If the quark is invalid
137	*/
138	public void incrementAttribute(long t, int attributeQuark)
139	throws StateValueTypeException, TimeRangeException,
140	AttributeNotFoundException;
141
142	/**
143	* "Push" helper method. This uses the given integer attribute as a stack:
144	* The value of that attribute will represent the stack depth (always >= 1).
145	* Sub-attributes will be created, their base-name will be the position in
146	* the stack (1, 2, etc.) and their value will be the state value 'value'
147	* that was pushed to this position.
148	*
149	* @param t
150	* Timestamp of the state change
151	* @param value
152	* State value to assign to this stack position.
153	* @param attributeQuark
154	* The base attribute to use as a stack. If it does not exist if
155	* will be created (with depth = 1)
156	* @throws TimeRangeException
157	* If the requested timestamp is invalid
158	* @throws AttributeNotFoundException
159	* If the attribute is invalid
160	* @throws StateValueTypeException
161	* If the attribute 'attributeQuark' already exists, but is not
162	* of integer type.
163	*/
164	public void pushAttribute(long t, ITmfStateValue value, int attributeQuark)
165	throws TimeRangeException, AttributeNotFoundException,
166	StateValueTypeException;
167
168	/**
169	* Antagonist of the pushAttribute(), pops the top-most attribute on the
170	* stack-attribute. If this brings it back to depth = 0, the attribute is
171	* kept with depth = 0. If the value is already 0, or if the attribute
172	* doesn't exist, nothing is done.
173	*
174	* @param t
175	* Timestamp of the state change
176	* @param attributeQuark
177	* Quark of the stack-attribute to pop
178	* @throws AttributeNotFoundException
179	* If the attribute is invalid
180	* @throws TimeRangeException
181	* If the timestamp is invalid
182	* @throws StateValueTypeException
183	* If the target attribute already exists, but its state value
184	* type is invalid (not an integer)
185	*/
186	public void popAttribute(long t, int attributeQuark)
187	throws AttributeNotFoundException, TimeRangeException,
188	StateValueTypeException;
189
190	/**
191	* Remove attribute method. Similar to the above modify- methods, with value
192	* = 0 / null, except we will also "nullify" all the sub-contents of the
193	* requested path (a bit like "rm -rf")
194	*
195	* @param t
196	* Timestamp of the state change
197	* @param attributeQuark
198	* Attribute to remove
199	* @throws TimeRangeException
200	* If the timestamp is invalid
201	* @throws AttributeNotFoundException
202	* If the quark is invalid
203	*/
204	public void removeAttribute(long t, int attributeQuark)
205	throws TimeRangeException, AttributeNotFoundException;
206
207	/**
208	* Method to close off the History Provider. This happens for example when
209	* we are done reading an off-line trace. First we close the TransientState,
210	* commit it to the Provider, mark it as inactive, then we write the
211	* Attribute Tree somewhere so we can reopen it later.
212	*
213	* @param endTime
214	* The requested End Time of the history, since it could be
215	* bigger than the timestamp of the last event or state change we
216	* have seen. All "ongoing" states will be extended until this
217	* 'endTime'.
218	* @throws TimeRangeException
219	* If the passed endTime doesn't make sense (for example, if
220	* it's earlier than the latest time) and the backend doesn't
221	* know how to handle it.
222	*/
223	public void closeHistory(long endTime) throws TimeRangeException;
224	}