diff options
| author | Alexandre Montplaisir | 2012-06-11 21:07:36 +0000 |
|---|---|---|
| committer | Alexandre Montplaisir | 2012-06-11 21:23:53 +0000 |
| commit | bc255d69eeafc6fe3761f89472c505923066f8b3 (patch) | |
| tree | 77ea03863581072cbffd99d75533d3c7d058f9d8 | |
| parent | 56d49af93d21759210af70dc99fa5d45e18c663a (diff) | |
| download | org.eclipse.linuxtools-bc255d69eeafc6fe3761f89472c505923066f8b3.tar.gz org.eclipse.linuxtools-bc255d69eeafc6fe3761f89472c505923066f8b3.tar.xz org.eclipse.linuxtools-bc255d69eeafc6fe3761f89472c505923066f8b3.zip | |
Update Javadoc for the public API in legacy LTTng
Signed-off-by: Alexandre Montplaisir <alexmonthy@voxpopuli.im>
10 files changed, 899 insertions, 562 deletions
diff --git a/lttng/org.eclipse.linuxtools.ctf.parser/src/org/eclipse/linuxtools/ctf/parser/CTFParser.java b/lttng/org.eclipse.linuxtools.ctf.parser/src/org/eclipse/linuxtools/ctf/parser/CTFParser.java index c52c3acc68..b300357f11 100644 --- a/lttng/org.eclipse.linuxtools.ctf.parser/src/org/eclipse/linuxtools/ctf/parser/CTFParser.java +++ b/lttng/org.eclipse.linuxtools.ctf.parser/src/org/eclipse/linuxtools/ctf/parser/CTFParser.java @@ -34,7 +34,7 @@ import org.antlr.runtime.tree.TreeAdaptor; * @author Matthew Khouzam and Antlr * */ -@SuppressWarnings({ "nls", "unused", "unchecked", "rawtypes","null", "javadoc" }) +@SuppressWarnings({"nls", "unused", "unchecked", "rawtypes", "null", "javadoc"}) public class CTFParser extends Parser { public static final String[] tokenNames = new String[] { "<invalid>", "<EOR>", "<DOWN>", "<UP>", "ALIGNTOK", "CONSTTOK", "CHARTOK", diff --git a/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/JniEvent.java b/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/JniEvent.java index 247bf11880..af2cde7b9c 100644 --- a/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/JniEvent.java +++ b/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/JniEvent.java @@ -1,12 +1,12 @@ package org.eclipse.linuxtools.lttng.jni; /******************************************************************************* * Copyright (c) 2009 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: * William Bourque (wbourque@gmail.com) - Initial API and implementation *******************************************************************************/ @@ -22,22 +22,22 @@ import org.eclipse.linuxtools.internal.lttng.jni.exception.JniNoSuchEventExcepti /** * <b><u>JniEvent</u></b> <p> - * + * * A JniEvent has the actual content that got traced by Lttng.<br> * Provides access to the LttEvent C structure in java. <p> - * + * * Most important fields in the JniEvent are : * <ul> * <li>an event time, which is a digested timestamp. * </ul> * Note that the JniEvent content is not directly accessibe and should be obtained * using the parseAllFields() or parseFieldBy...() methods. - * + * * <b>NOTE</b><p> * This class is ABSTRACT, you need to extends it to support your specific LTTng version.<p> - * + * */ -public abstract class JniEvent extends Jni_C_Common implements Comparable<JniEvent> +public abstract class JniEvent extends Jni_C_Common implements Comparable<JniEvent> { // Variables to detect if the event have been filled at least once // this make possible the detection of "uninitialized" struct in Ltt @@ -65,7 +65,7 @@ public abstract class JniEvent extends Jni_C_Common implements Comparable<JniEve protected native int ltt_readNextEvent(int libId, long tracefilePtr); protected native int ltt_seekEvent(int libId, long tracefilePtr, JniTime givenTime); protected native int ltt_positionToFirstEvent(int libId, long tracefilePtr); - + // Native access functions protected native long ltt_getTracefilePtr(int libId, long eventPtr); protected native long ltt_getBlock(int libId, long eventPtr); @@ -79,14 +79,14 @@ public abstract class JniEvent extends Jni_C_Common implements Comparable<JniEve protected native long ltt_getEventSize(int libId, long eventPtr); protected native int ltt_getCount(int libId, long eventPtr); protected native long ltt_getOverflowNanoSeconds(int libId, long eventPtr); - + // This method can be use to obtain the content as byte array // Warning : untested! protected native void ltt_getDataContent(int libId, long eventPtr, long dataSize, byte[] returnedContent); - + // Debug native function, ask LTT to print event structure protected native void ltt_printEvent(int libId, long eventPtr); - + /** * Default constructor is forbidden */ @@ -95,8 +95,8 @@ public abstract class JniEvent extends Jni_C_Common implements Comparable<JniEve /** * Copy constructor.<p> - * - * @param oldEvent Reference to the JniEvent you want to copy. + * + * @param oldEvent Reference to the JniEvent you want to copy. */ public JniEvent(JniEvent oldEvent) { thisEventPtr = oldEvent.thisEventPtr; @@ -107,60 +107,67 @@ public abstract class JniEvent extends Jni_C_Common implements Comparable<JniEve tracefilePtr = oldEvent.tracefilePtr; eventTime = oldEvent.eventTime; } - + /** - * Constructor with parameters<p> - * - * This constructor could throw. It will happen if an event can not be populated on <u>first read</u>.<br> - * In that case, the parent tracefile is probably useless and should be deleted. - * - * @param newEventPtr C pointer (converted in long) of the LttEvent C structure. - * @param newMarkersMap Reference an already populated HashMap of JniMarker objects - * @param newParentTracefile Reference to the parent JniTracefile of this JniEvent - * + * Constructor with parameters + * <p> + * + * This constructor could throw. It will happen if an event can not be + * populated on <u>first read</u>.<br> + * In that case, the parent tracefile is probably useless and should be + * deleted. + * + * @param newEventPtr + * C pointer (converted in long) of the LttEvent C structure. + * @param newMarkersMap + * Reference an already populated HashMap of JniMarker objects + * @param newParentTracefile + * Reference to the parent JniTracefile of this JniEvent + * * @exception JniException - * + * If the JNI call fails + * * @see org.eclipse.linuxtools.internal.lttng.jni.common.Jni_C_Pointer_And_Library_Id * @see org.eclipse.linuxtools.lttng.jni.JniMarker * @see org.eclipse.linuxtools.lttng.jni.JniTracefile */ - public JniEvent(Jni_C_Pointer_And_Library_Id newEventPtr, HashMap<Integer, JniMarker> newMarkersMap, JniTracefile newParentTracefile) throws JniException { - - // Basic test to make sure we didn't get null/empty value + public JniEvent(Jni_C_Pointer_And_Library_Id newEventPtr, + HashMap<Integer, JniMarker> newMarkersMap, + JniTracefile newParentTracefile) throws JniException { + + // Basic test to make sure we didn't get null/empty value if ((newEventPtr.getPointer() == NULL) - || (newMarkersMap == null) + || (newMarkersMap == null) || (newMarkersMap.size() == 0) || (newParentTracefile == null)) { throw new JniEventException("Null or empty value passed to constructor, object is invalid! (JniEvent)"); //$NON-NLS-1$ } - + thisEventPtr = newEventPtr; tracefilePtr = newParentTracefile.getTracefilePtr(); markersMap = newMarkersMap; parentTracefile = newParentTracefile; eventTime = new JniTime(); - + // Try to move to the first event - // If the event is Out of Range (ERANGE) at the first read, + // If the event is Out of Range (ERANGE) at the first read, // this event type will never be usable. // In that case, throw JniNoSuchEventException to warn the tracefile. eventState = positionToFirstEvent(); if (eventState != EOK) { throw new JniNoSuchEventException("Object not populated, unusable. There is probably no event of that type in the trace. (JniEvent)"); //$NON-NLS-1$ } - else { - populateEventInformation(); - } + populateEventInformation(); } /** * Move to the next event and populate the java object with LttEvent structure.<p> - * + * * If the move fails, the event will not get populated and the last event data will still be available. - * + * * @return LTT read status, as defined in Jni_C_Constant. - * + * * @see org.eclipse.linuxtools.internal.lttng.jni.common.Jni_C_Constant */ public int readNextEvent() { @@ -170,28 +177,38 @@ public abstract class JniEvent extends Jni_C_Common implements Comparable<JniEve if (eventState == EOK) { populateEventInformation(); } - + return eventState; } /** - * Seek to a certain time.<p> - * - * Seek to a certain time and read event at this exact time or the next one if there is no event there.<p> - * - * Note that this function can seek in an invalid position if the timestamp is after the last event.<br> - * In that case, a seek back would be required to get back to a consistent state.<p> - * - * If the seek fails, the event will not get populated and the last event data will still be available.<p> - * + * Seek to a certain time. + * <p> + * + * Seek to a certain time and read event at this exact time or the next one + * if there is no event there. + * <p> + * + * Note that this function can seek in an invalid position if the timestamp + * is after the last event.<br> + * In that case, a seek back would be required to get back to a consistent + * state. + * <p> + * + * If the seek fails, the event will not get populated and the last event + * data will still be available. + * <p> + * + * @param seekTime + * The timestamp to which we want to seek * @return LTT read status, as defined in Jni_C_Constant - * + * * @see org.eclipse.linuxtools.internal.lttng.jni.common.Jni_C_Constant */ public int seekToTime(JniTime seekTime) { // Ask Ltt to read the next event for this particular tracefile eventState = ltt_seekEvent(tracefilePtr.getLibraryId(), tracefilePtr.getPointer(), seekTime); - + // If the event state is sane populate it if (eventState == EOK) { populateEventInformation(); @@ -201,14 +218,21 @@ public abstract class JniEvent extends Jni_C_Common implements Comparable<JniEve } /** - * Try to seek to a certain time and seek back if it failed.<p> - * - * Seek to a certain time and read event at this exact time or the next one if there is no event there.<p> - * - * If the seek fails, we will seek back to the previous position, so the event will stay in a consistent state.<p> - * + * Try to seek to a certain time and seek back if it failed. + * <p> + * + * Seek to a certain time and read event at this exact time or the next one + * if there is no event there. + * <p> + * + * If the seek fails, we will seek back to the previous position, so the + * event will stay in a consistent state. + * <p> + * + * @param seekTime + * The target timestamp we will try to seek to * @return LTT read status, as defined in Jni_C_Constant - * + * * @see org.eclipse.linuxtools.internal.lttng.jni.common.Jni_C_Constant */ public int seekOrFallBack(JniTime seekTime) { @@ -232,26 +256,26 @@ public abstract class JniEvent extends Jni_C_Common implements Comparable<JniEve /** * Position on the first event in the tracefile.<p> - * + * * The function return the read status after the first event.<p> - * + * * A status different of EOK probably means there is no event associated to this tracefile. - * + * * @return LTT read status, as defined in Jni_C_Constant - * + * * @see org.eclipse.linuxtools.internal.lttng.jni.common.Jni_C_Constant */ protected int positionToFirstEvent() { eventState = ltt_positionToFirstEvent(tracefilePtr.getLibraryId(), tracefilePtr.getPointer()); - + return eventState; } - + /** * Obtain a marker associated with this tracefile's event. - * + * * @return Reference to the marker for this tracefile's event or null if none. - * + * * @see org.eclipse.linuxtools.lttng.jni.JniMarker */ public JniMarker requestEventMarker() { @@ -260,10 +284,10 @@ public abstract class JniEvent extends Jni_C_Common implements Comparable<JniEve /** * Obtain the raw data of a LttEvent object.<p> - * + * * The data will be in raw C bytes, not java bytes.<br> * Note : This function is mostly untested and provided "as is". - * + * * @return Bytes array of raw data (contain raw C bytes). */ public byte[] requestEventContent() { @@ -273,14 +297,14 @@ public abstract class JniEvent extends Jni_C_Common implements Comparable<JniEve return dataContent; } - + /** * Obtain an event source.<p> - * + * * This is not implemented yet and will always return "Kernel core" for now. - * - * @return Reference to the JniMarker object for this event or null if none. - * + * + * @return Reference to the JniMarker object for this event or null if none. + * * @see org.eclipse.linuxtools.lttng.jni.JniMarker */ public String requestEventSource() { @@ -288,76 +312,98 @@ public abstract class JniEvent extends Jni_C_Common implements Comparable<JniEve // No "Source" of event exists in Ltt so far // It would be a good addition to have a way to detect where an event come // from, like "kernel" or "userspace" - // + // return "Kernel Core"; //$NON-NLS-1$ } - + /** * Parse a particular field in the event payload, identified by its id (position).<p> - * + * * Note : Position are relative to an event marker (i.e. requestEventMarker().getMarkerFieldsArrayList() ) - * + * * @param fieldId Position of the field to parse. - * + * * @return Object that contain the parsed payload - * + * * @see org.eclipse.linuxtools.lttng.jni.JniParser */ public Object parseFieldById(int fieldId) { return JniParser.parseField(this, fieldId); } - + /** * Parse a particular field in the event payload, identified by its name.<p> - * + * * Note : Name are relative to an event marker (i.e. requestEventMarker().getMarkerFieldsHashMap() ) - * + * * @param fieldName Position of the field to parse. - * + * * @return Object that contain the parsed payload - * + * * @see org.eclipse.linuxtools.lttng.jni.JniParser */ public Object parseFieldByName(String fieldName) { return JniParser.parseField(this, fieldName); } - + /** * Method to parse all the event payload.<p> - * + * * @return HashMap<String, Object> which is the parsedContent objects and their name as key. - * - * @see org.eclipse.linuxtools.lttng.jni.JniParser + * + * @see org.eclipse.linuxtools.lttng.jni.JniParser */ public HashMap<String, Object> parseAllFields() { return JniParser.parseAllFields(this); } - /* + /* * This function populates the event data with data from LTT - * + * * NOTE : To get better performance, we copy very few data into memory here - * + * */ private void populateEventInformation() { // We need to save the time, as it is not a primitive (can't be dynamically called in getter) eventTime.setTime(ltt_getNanosencondsTime(thisEventPtr.getLibraryId(), thisEventPtr.getPointer())); } - + + /** + * Get this event's timestamp + * + * @return The timestamp, as a JniTime + */ public JniTime getEventTime() { return eventTime; } - - // *** To get better performance, all getter belows call LTT directly **** + + // *** To get better performance, all getters below call LTT directly **** // That way, we can avoid copying data into memory + + /** + * Get this event's marker ID. This is a direct call through JNI. + * + * @return The marker ID + */ public int getEventMarkerId() { return ltt_getEventMarkerId(thisEventPtr.getLibraryId(), thisEventPtr.getPointer()); } + /** + * Get this event's data size. This is a direct call through JNI. + * + * @return The data size + */ public long getEventDataSize() { - return ltt_getEventDataSize(thisEventPtr.getLibraryId(), thisEventPtr.getPointer()); + return ltt_getEventDataSize(thisEventPtr.getLibraryId(), + thisEventPtr.getPointer()); } + /** + * Get the markers for this event. This does NOT go through JNI. + * + * @return The (java) Map of markers + */ public HashMap<Integer, JniMarker> getMarkersMap() { return markersMap; } @@ -367,9 +413,9 @@ public abstract class JniEvent extends Jni_C_Common implements Comparable<JniEve * <br> * The pointer should only be used <u>INTERNALY</u>, do not use unless you * know what you are doing. - * + * * @return The actual (long converted) pointer or NULL. - * + * * @see org.eclipse.linuxtools.internal.lttng.jni.common.Jni_C_Pointer_And_Library_Id */ public Jni_C_Pointer_And_Library_Id getTracefilePtr() { @@ -381,15 +427,20 @@ public abstract class JniEvent extends Jni_C_Common implements Comparable<JniEve * <br> * The pointer should only be used <u>INTERNALY</u>, do not use unless you * know what you are doing. - * + * * @return The actual (long converted) pointer or NULL. - * + * * @see org.eclipse.linuxtools.internal.lttng.jni.common.Jni_C_Pointer_And_Library_Id */ public Jni_C_Pointer_And_Library_Id getEventPtr() { return thisEventPtr; } + /** + * Get this event's state + * + * @return The integer value representing the state + */ public int getEventState() { return eventState; } @@ -397,8 +448,8 @@ public abstract class JniEvent extends Jni_C_Common implements Comparable<JniEve /** * Getter to the parent tracefile for this event. * - * @return The parent tracefile - * + * @return The parent tracefile + * * @see org.eclipse.linuxtools.lttng.jni.JniTracefile */ public JniTracefile getParentTracefile() { @@ -453,7 +504,7 @@ public abstract class JniEvent extends Jni_C_Common implements Comparable<JniEve * <p> * This will compare the current JNIEvent with a passed one by timestamp AND tracefile ("type").<br> * If both are equal but type differs, current event is considered to be older (-1 returned). - * + * * @return -1 if given event happens before, 0 if equal, 1 if passed event happens after. */ @Override @@ -475,22 +526,22 @@ public abstract class JniEvent extends Jni_C_Common implements Comparable<JniEve } return eventComparaison; } - + /** - * Print information for this event. + * Print information for this event. * <u>Intended to debug</u><br> - * - * This function will call Ltt to print, so information printed will be + * + * This function will call Ltt to print, so information printed will be * the one from the C structure, not the one populated in java.<p> */ public void printEventInformation() { ltt_printEvent(thisEventPtr.getLibraryId(), thisEventPtr.getPointer()); } - + /** - * toString() method. + * toString() method. * <u>Intended to debug.</u><p> - * + * * @return Attributes of the object concatenated in String */ @Override @@ -508,5 +559,5 @@ public abstract class JniEvent extends Jni_C_Common implements Comparable<JniEve return returnData; } - + } diff --git a/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/JniMarker.java b/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/JniMarker.java index 900534a0af..30f3da1871 100644 --- a/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/JniMarker.java +++ b/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/JniMarker.java @@ -1,12 +1,12 @@ package org.eclipse.linuxtools.lttng.jni; /******************************************************************************* * Copyright (c) 2009 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: * William Bourque (wbourque@gmail.com) - Initial API and implementation *******************************************************************************/ @@ -20,23 +20,23 @@ import org.eclipse.linuxtools.internal.lttng.jni.exception.JniMarkerException; /** * <b><u>JniMarker</u></b><p> - * + * * A JniMarker contain information how to interpret the unparsed content (payload) of an event.<br> * Each JniMarker contains several MarkerFields for each fields in the event's payload. - * - * Provides access to the marker_info C structure (from LTT) in java. - * + * + * Provides access to the marker_info C structure (from LTT) in java. + * * Most important fields in the JniMarker are : * <ul> * <li> the name of the marker in String * <li> an overview of the marker format (in C style printf format) * <li> a reference to an ArrayList that contains MarkerFields object of this JniMarker * </ul> - * + * * <b>NOTE</b><p> * This class is ABSTRACT, you need to extends it to support your specific LTTng version.<br> * Please look at the abstract functions to override at the bottom of this file.<p> - * + * */ public abstract class JniMarker extends Jni_C_Common { @@ -45,7 +45,7 @@ public abstract class JniMarker extends Jni_C_Common private String name = ""; //$NON-NLS-1$ private String formatOverview = ""; //$NON-NLS-1$ - + // These two contains hold references to the same MarkerField object // The ArrayList can be used to efficiently find a field by its position // The HashMap can be used to find a field by its name @@ -53,7 +53,7 @@ public abstract class JniMarker extends Jni_C_Common private ArrayList<JniMarkerField> markerFieldsArrayList = null; // Native access method - protected native String ltt_getName(int libId, long markerPtr); + protected native String ltt_getName(int libId, long markerPtr); protected native String ltt_getFormatOverview(int libId, long markerPtr); protected native long ltt_getSize(int libId, long markerPtr); protected native short ltt_getLargestAlign(int libId, long markerPtr); @@ -73,11 +73,11 @@ public abstract class JniMarker extends Jni_C_Common */ protected JniMarker() { } - + /** * Copy constructor.<p> - * - * @param oldMarker Reference to the JniMarker you want to copy. + * + * @param oldMarker Reference to the JniMarker you want to copy. */ public JniMarker(JniMarker oldMarker) { thisMarkerPtr = oldMarker.thisMarkerPtr; @@ -89,11 +89,13 @@ public abstract class JniMarker extends Jni_C_Common } /** - * Constructor, using pointer.<p> - * - * @param newMarkerPtr Pointer to a C marker_info structure - * + * Constructor, using pointer. + * <p> + * + * @param newMarkerPtr + * Pointer to a C marker_info structure * @exception JniException + * If the JNI call fails */ public JniMarker(Jni_C_Pointer_And_Library_Id newMarkerPtr) throws JniException { thisMarkerPtr = newMarkerPtr; @@ -104,29 +106,27 @@ public abstract class JniMarker extends Jni_C_Common populateMarkerInformation(); } - - /* + + /** * This function populates the marker data with data from LTT - * */ private void populateMarkerInformation() throws JniException { if (thisMarkerPtr.getPointer() == NULL) { throw new JniMarkerException("Pointer is NULL, trace closed? (populateMarkerInformatOverviewion)"); //$NON-NLS-1$ - } else { - name = ltt_getName(thisMarkerPtr.getLibraryId(), thisMarkerPtr.getPointer()); - formatOverview = ltt_getFormatOverview(thisMarkerPtr.getLibraryId(), thisMarkerPtr.getPointer()); - // To fill the markerFieldArray is a bit different - ltt_getAllMarkerFields(thisMarkerPtr.getLibraryId(), thisMarkerPtr.getPointer()); } + name = ltt_getName(thisMarkerPtr.getLibraryId(), thisMarkerPtr.getPointer()); + formatOverview = ltt_getFormatOverview(thisMarkerPtr.getLibraryId(), thisMarkerPtr.getPointer()); + // To fill the markerFieldArray is a bit different + ltt_getAllMarkerFields(thisMarkerPtr.getLibraryId(), thisMarkerPtr.getPointer()); } - /* + /** * Fills a map of all the JniMarkerField associated with this JniMarker. - * + * * Note: This function is called from C and there is no way to propagate * exception back to the caller without crashing JNI. Therefore, it MUST * catch all exceptions. - * + * * @param markerName Name of the parent marker * @param markerFieldPtr C Pointer (converted in long) to marker_field C Structure */ @@ -137,62 +137,83 @@ public abstract class JniMarker extends Jni_C_Common JniMarkerField newMarkerField = allocateNewJniMarkerField( new Jni_C_Pointer_And_Library_Id(thisMarkerPtr.getLibraryId(), markerFieldPtr)); markerFieldsArrayList.add(newMarkerField); markerFieldsHashMap.put(markerFieldName, newMarkerField); - + } catch (JniException e) { printlnC(thisMarkerPtr.getLibraryId(), "Failed to add marker field " + markerFieldName + " to marker fields list!(addMarkerFieldFromC)\n\tException raised : " + e.toString() ); //$NON-NLS-1$ //$NON-NLS-2$ } } - // Access to class variable. Most of them doesn't have setter + // Access to class variables. Most of them doesn't have setters + + /** + * Get the name of this marker + * + * @return The name + */ public String getName() { return name; } + /** + * Get the format overview + * + * @return The format overview, as one string + */ public String getFormatOverview() { return formatOverview; } + /** + * Get the marker fields as a hashmap + * + * @return The map of fields + */ public HashMap<String,JniMarkerField> getMarkerFieldsHashMap() { return markerFieldsHashMap; } - + + /** + * Get the marker fields as an array list + * + * @return The array list of fields + */ public ArrayList<JniMarkerField> getMarkerFieldsArrayList() { return markerFieldsArrayList; } - + /** * Pointer to the marker_info C structure.<p> - * + * * The pointer should only be used <u>INTERNALY</u>, do not use unless you * know what you are doing.<p> - * + * * @return The actual (long converted) pointer or NULL - * + * * @see org.eclipse.linuxtools.internal.lttng.jni.common.Jni_C_Pointer_And_Library_Id */ public Jni_C_Pointer_And_Library_Id getMarkerPtr() { return thisMarkerPtr; } - - + + /** - * Print information for this JniMarker. + * Print information for this JniMarker. * <u>Intended to debug</u><br> - * - * This function will call Ltt to print, so information printed will be the one from + * + * This function will call Ltt to print, so information printed will be the one from * the C structure, not the one populated in java.<p> - * + * * This function will not throw but will complain loudly if pointer is NULL */ public void printMarkerInformation() { ltt_printMarker(thisMarkerPtr.getLibraryId(), thisMarkerPtr.getPointer()); } - + /** - * Print information for ALL marker fields for this marker. + * Print information for ALL marker fields for this marker. * <u>Intended to debug</u><br> - * - * This function will call Ltt to print, so information printed will be the one from + * + * This function will call Ltt to print, so information printed will be the one from * the C structure, not the one populated in java. */ public void printAllMarkerFieldsInformation() { @@ -202,11 +223,11 @@ public abstract class JniMarker extends Jni_C_Common printlnC(thisMarkerPtr.getLibraryId(), allMarkersField[pos].toString()); } } - + /** - * toString() method. + * toString() method. * <u>Intended to debug</u><br> - * + * * @return Attributes of the object concatenated in String */ @Override @@ -217,16 +238,16 @@ public abstract class JniMarker extends Jni_C_Common returnData += "name : " + name + "\n"; returnData += "formatOverview : " + formatOverview + "\n"; returnData += "markerFieldArrayList : " + markerFieldsArrayList.hashCode() + " (size : " + markerFieldsArrayList.size() + " )" + "\n"; - + return returnData; } - - + + // **************************** // **** ABSTRACT FUNCTIONS **** // You MUST override those in your version specific implementation - - + + /** * Function place holder to allocate a new JniMarkerField.<p> * <br> @@ -234,16 +255,16 @@ public abstract class JniMarker extends Jni_C_Common * Effect of this function should be the same (allocate a fresh new JniMarkerField).<br> * <br> * <b>!! Override this with you version specific implementation.</b><br> - * + * * @param newMarkerFieldPtr The pointer and library id of an already opened marker_field C Structure - * + * * @return The newly allocated JniMarkerField of the correct version - * + * * @throws JniException The construction (allocation) failed. - * + * * @see org.eclipse.linuxtools.internal.lttng.jni.common.Jni_C_Pointer_And_Library_Id * @see org.eclipse.linuxtools.lttng.jni.JniMarkerField */ public abstract JniMarkerField allocateNewJniMarkerField(Jni_C_Pointer_And_Library_Id newMarkerFieldPtr) throws JniException; - + } diff --git a/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/JniMarkerField.java b/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/JniMarkerField.java index 0e4f1b83c3..0bf906496d 100644 --- a/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/JniMarkerField.java +++ b/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/JniMarkerField.java @@ -8,18 +8,18 @@ import org.eclipse.linuxtools.internal.lttng.jni.exception.JniMarkerFieldExcepti /** * <b><u>JniMarkerField</u></b> <p> * A JniMarkerField is one of the field of the unparsed content (payload) of an event. <p> - * + * * Provides access to the marker_field C structure (from LTT) in java.<p> - * + * * Most important attributes in the JniMarkerField are : * <ul> * <li> the name (field) of in String * <li> the marker field format (in C style printf format) * </ul> - * + * * <b>NOTE</b><p> * This class is ABSTRACT, you need to extends it to support your specific LTTng version.<p> - * + * */ public abstract class JniMarkerField extends Jni_C_Common { @@ -28,7 +28,7 @@ public abstract class JniMarkerField extends Jni_C_Common private String field = ""; //$NON-NLS-1$ private String format = ""; //$NON-NLS-1$ - + // Native access method protected native String ltt_getField(int libId, long markerFieldPtr); protected native int ltt_getType(int libId, long markerFieldPtr); @@ -50,8 +50,8 @@ public abstract class JniMarkerField extends Jni_C_Common /** * Copy constructor.<p> - * - * @param oldMarkerField Reference to the JniMarkerField you want to copy. + * + * @param oldMarkerField Reference to the JniMarkerField you want to copy. */ public JniMarkerField(JniMarkerField oldMarkerField) { thisMarkerFieldPtr = oldMarkerField.getMarkerFieldPtr(); @@ -60,12 +60,14 @@ public abstract class JniMarkerField extends Jni_C_Common } /** - * Constructor, using pointer.<p> - * - * @param newMarkerFieldPtr Pointer to a C marker_field structure - * + * Constructor, using pointer. + * <p> + * + * @param newMarkerFieldPtr + * Pointer to a C marker_field structure * @exception JniException - * + * If the JNI call fails + * * @see org.eclipse.linuxtools.internal.lttng.jni.common.Jni_C_Pointer_And_Library_Id */ public JniMarkerField(Jni_C_Pointer_And_Library_Id newMarkerFieldPtr) throws JniException { @@ -75,56 +77,65 @@ public abstract class JniMarkerField extends Jni_C_Common populateMarkerFieldInformation(); } - /* + /* * This function populates the marker field data with data from LTT - * + * */ private void populateMarkerFieldInformation() throws JniException { if (thisMarkerFieldPtr.getPointer() == NULL) { throw new JniMarkerFieldException( "Pointer is NULL, trace closed? (populateMarkerInformation)"); //$NON-NLS-1$ - } else { - field = ltt_getField(thisMarkerFieldPtr.getLibraryId(), thisMarkerFieldPtr.getPointer()); - format = ltt_getFormat(thisMarkerFieldPtr.getLibraryId(), thisMarkerFieldPtr.getPointer()); } + field = ltt_getField(thisMarkerFieldPtr.getLibraryId(), thisMarkerFieldPtr.getPointer()); + format = ltt_getFormat(thisMarkerFieldPtr.getLibraryId(), thisMarkerFieldPtr.getPointer()); } + /** + * Get the field of this marker + * + * @return The field name + */ public String getField() { return field; } + /** + * Get the format of this marker + * + * @return The format, as a String + */ public String getFormat() { return format; } /** * Pointer to the marker_field C structure.<p> - * + * * The pointer should only be used <u>INTERNALY</u>, do not use these unless you * know what you are doing.<p> - * + * * @return The actual (long converted) pointer or NULL - * + * * @see org.eclipse.linuxtools.internal.lttng.jni.common.Jni_C_Pointer_And_Library_Id */ public Jni_C_Pointer_And_Library_Id getMarkerFieldPtr() { return thisMarkerFieldPtr; } - + /** * Print information for this event. <u>Intended to debug</u><br> - * - * This function will call Ltt to print, so information printed will be the one from + * + * This function will call Ltt to print, so information printed will be the one from * the C structure, not the one populated in java.<p> */ public void printMarkerFieldInformation() { ltt_printMarkerField(thisMarkerFieldPtr.getLibraryId(), thisMarkerFieldPtr.getPointer()); } - + /** - * toString() method. + * toString() method. * <u>Intended to debug</u><br> - * + * * @return Attributes of the object concatenated in String */ @Override @@ -133,8 +144,8 @@ public abstract class JniMarkerField extends Jni_C_Common String returnData = ""; returnData += "field : " + field + "\n"; returnData += "format : " + format + "\n"; - + return returnData; } - + } diff --git a/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/JniParser.java b/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/JniParser.java index b070b14ae5..6ad7e07a1c 100644 --- a/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/JniParser.java +++ b/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/JniParser.java @@ -1,12 +1,12 @@ package org.eclipse.linuxtools.lttng.jni; /******************************************************************************* * Copyright (c) 2009 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: * William Bourque (wbourque@gmail.com) - Initial API and implementation *******************************************************************************/ @@ -19,121 +19,121 @@ import org.eclipse.linuxtools.internal.lttng.jni.common.Jni_C_Pointer; /** * <b><u>JniParser</u></b><p> - * + * * JniParser is used to parse an event payload into something usable.<p> - * + * * All methods are static, the parser shouldn't be instantiated. - * + * * <b>NOTE</b><p> * This class is ABSTRACT, you need to extends it to support your specific LTTng version.<p> - * + * */ public abstract class JniParser extends Jni_C_Common { protected static native void ltt_getParsedData(int libId, ParsedObjectContent parseddata, long eventPtr, long markerFieldPtr); - + // *** HACK *** // We cannot use "Object" directly as java does not support swapping primitive value // We either need to create a new object type or to use a "non-primitive" type that have "Setter()" functions // Another (ugly) hack would be to pass an array to modify the reference's reference. // *** private static ParsedObjectContent parsedData = new ParsedObjectContent(); - + /* * Default constructor is forbidden */ protected JniParser() { } - - + + /** * Method to parse a single field identified by its id.<p> - * + * * All parsing will be done on C side as we need LTT functions. - * - * @param eventToParse The jni event we want to parse. + * + * @param eventToParse The jni event we want to parse. * @param fieldPosition The position (or id) of the field we want to parse - * + * * @return An Object that contain the JniEvent payload parsed by the C, or null, if if was impossible to parse (i.e., wrong position) - * + * * @see org.eclipse.linuxtools.lttng.jni.JniEvent */ static public Object parseField(JniEvent eventToParse, int fieldPosition) { - + // Sanity check if ( (fieldPosition < 0) || ( fieldPosition >= eventToParse.requestEventMarker().getMarkerFieldsArrayList().size() ) ){ return null; } - + JniMarkerField tmpField = eventToParse.requestEventMarker().getMarkerFieldsArrayList().get(fieldPosition); - + // Call the parsing function in C. The result will be put in parsedData object ltt_getParsedData(eventToParse.getEventPtr().getLibraryId(), parsedData, eventToParse.getEventPtr().getPointer(), tmpField.getMarkerFieldPtr().getPointer()); - + return parsedData.getData(); } - - + + /** * Method to parse a single field identified by its name.<p> - * + * * All parsing will be done on C side as we need LTT functions. - * - * @param eventToParse The jni event we want to parse. + * + * @param eventToParse The jni event we want to parse. * @param fieldName The name of the field we want to parse. - * + * * @return An Object that contain the JniEvent payload parsed by the C, or null, if if was impossible to parse (i.e., wrong position) - * + * * @see org.eclipse.linuxtools.lttng.jni.JniEvent */ static public Object parseField(JniEvent eventToParse, String fieldName) { - + JniMarkerField tmpField = eventToParse.requestEventMarker().getMarkerFieldsHashMap().get(fieldName); - + // return immediately if there is no field by that name if ( tmpField == null ) { return null; } - + ltt_getParsedData(eventToParse.getEventPtr().getLibraryId(), parsedData, eventToParse.getEventPtr().getPointer(), tmpField.getMarkerFieldPtr().getPointer()); - + return parsedData.getData(); } - - - + + + /** * Method to parse all fields at once.<p> - * + * * All parsing will be done on C side as we need LTT functions. - * - * @param eventToParse The jni event we want to parse. + * + * @param eventToParse The jni event we want to parse. * @return An HashMap of Object that contain the is the JniEvent's payload parsed by the C - * + * * @see org.eclipse.linuxtools.lttng.jni.JniEvent */ static public HashMap<String, Object> parseAllFields(JniEvent eventToParse) { HashMap<String,JniMarkerField> markerFieldData = eventToParse.requestEventMarker().getMarkerFieldsHashMap(); - + // This hashmap will contain the parsed content. // ParsedContent is a local class defined at the end of this file - + // *** HACK *** // We want (need?) the map that contain the parsed data to be in the same order as markerField map - // The "instinctive way" would be to use : + // The "instinctive way" would be to use : // HashMap<String, Object> parsedDataMap = new HashMap<String, Object>(nbMarkerField); // // However, we cannot ensure that the newly created hashmap will use the same order. // The hard way would be to override the default hash function for both hashmap // However, this is way easier to abuse the fact that both hashmap are of type <String, something...> - // Therefore we can abuse the java-cast with clone() : + // Therefore we can abuse the java-cast with clone() : // HashMap<String, Object> parsedDataMap = (HashMap<String, Object>)markerFieldData.clone(); - // Or even safer, use HashMap constructor to do so : + // Or even safer, use HashMap constructor to do so : HashMap<String, Object> parsedDataMap = new HashMap<String, Object>(markerFieldData); - + JniMarkerField newMarkerField = null; Iterator<String> iterator = markerFieldData.keySet().iterator(); - + while ( iterator.hasNext() ) { newMarkerField = markerFieldData.get(iterator.next()); // Call the C to parse the data @@ -141,18 +141,18 @@ public abstract class JniParser extends Jni_C_Common // Save the result into the HashMap parsedDataMap.put(newMarkerField.getField(), parsedData.getData() ); } - + return parsedDataMap; } - - - /* + + + /* * Add a parsed String value to the Array<br> * <br> * Note : this function will be called from the C side. * Note2: contentHolder is of type "Object" instead of "ParsedObjectContent" to be able to use the most generic function signature on the C side. * its goal is to give a generic interface to people that would like to use the JNI library - * + * * @param parsedArray Array where to store the value * @param fieldName The name of the parsed field * @param stringToAdd The parsed data to add @@ -162,29 +162,29 @@ public abstract class JniParser extends Jni_C_Common ((ParsedObjectContent)contentHolder).setData( stringToAdd); } - /* + /* * Add a parsed 64 bits Pointer value to the Array<br> * <br> * Note : this function will be called from the C side. * Note2: contentHolder is of type "Object" instead of "ParsedObjectContent" to be able to use the most generic function signature on the C side. * its goal is to give a generic interface to people that would like to use the JNI library - * + * * @param contentHolder Object where to store the parsed value * @param fieldName The name of the parsed field * @param pointerToAdd The parsed data to add (in 64 bits long!) * @param formatToAdd The format of the raw data */ static private void addLongPointerToParsingFromC(Object contentHolder, long pointerToAdd) { - ((ParsedObjectContent)contentHolder).setData( new Jni_C_Pointer((long) pointerToAdd)); + ((ParsedObjectContent)contentHolder).setData( new Jni_C_Pointer(pointerToAdd)); } - /* + /* * Add a parsed 32 bits Pointer value to the Array<br> * <br> * Note : this function will be called from the C side. * Note2: contentHolder is of type "Object" instead of "ParsedObjectContent" to be able to use the most generic function signature on the C side. * its goal is to give a generic interface to people that would like to use the JNI library - * + * * @param contentHolder Object where to store the parsed value * @param fieldName The name of the parsed field * @param pointerToAdd The parsed data to add (converted in 64 bits long!) @@ -194,13 +194,13 @@ public abstract class JniParser extends Jni_C_Common ((ParsedObjectContent)contentHolder).setData( new Jni_C_Pointer((int) pointerToAdd)); } - /* + /* * Add a parsed short value to the Array<br> * <br> * Note : this function will be called from the C side. * Note2: contentHolder is of type "Object" instead of "ParsedObjectContent" to be able to use the most generic function signature on the C side. * its goal is to give a generic interface to people that would like to use the JNI library - * + * * @param contentHolder Object where to store the parsed value * @param fieldName The name of the parsed field * @param shortToAdd The parsed data to add @@ -210,13 +210,13 @@ public abstract class JniParser extends Jni_C_Common ((ParsedObjectContent)contentHolder).setData( Short.valueOf(shortToAdd)); } - /* + /* * Add a parsed integer value to the Array<br> * <br> * Note : this function will be called from the C side. * Note2: contentHolder is of type "Object" instead of "ParsedObjectContent" to be able to use the most generic function signature on the C side. * its goal is to give a generic interface to people that would like to use the JNI library - * + * * @param contentHolder Object where to store the parsed value * @param fieldName The name of the parsed field * @param intToAdd The parsed data to add @@ -226,13 +226,13 @@ public abstract class JniParser extends Jni_C_Common ((ParsedObjectContent)contentHolder).setData( Integer.valueOf(intToAdd)); } - /* + /* * Add a parsed long value to the Array<br> * <br> * Note : this function will be called from the C side. * Note2: contentHolder is of type "Object" instead of "ParsedObjectContent" to be able to use the most generic function signature on the C side. * its goal is to give a generic interface to people that would like to use the JNI library - * + * * @param contentHolder Object where to store the parsed value * @param fieldName The name of the parsed field * @param longToAdd The parsed data to add @@ -242,13 +242,13 @@ public abstract class JniParser extends Jni_C_Common ((ParsedObjectContent)contentHolder).setData( Long.valueOf(longToAdd)); } - /* + /* * Add a parsed float value to the Array<br> * <br> * Note : this function will be called from the C side. * Note2: contentHolder is of type "Object" instead of "ParsedObjectContent" to be able to use the most generic function signature on the C side. * its goal is to give a generic interface to people that would like to use the JNI library - * + * * @param contentHolder Object where to store the parsed value * @param fieldName The name of the parsed field * @param floatToAdd The parsed data to add @@ -258,14 +258,14 @@ public abstract class JniParser extends Jni_C_Common ((ParsedObjectContent)contentHolder).setData( new Float(floatToAdd)); } - /* + /* * Add a parsed double value to the Array<br> * <br> * Note : this function will be called from the C side. * Note2: contentHolder is of type "Object" instead of "ParsedObjectContent" to be able to use the most generic function signature on the C side. * its goal is to give a generic interface to people that would like to use the JNI library - * - * + * + * * @param contentHolder Object where to store the parsed value * @param fieldName The name of the parsed field * @param doubleToAdd The parsed data to add @@ -274,23 +274,23 @@ public abstract class JniParser extends Jni_C_Common static private void addDoubleToParsingFromC(Object contentHolder, double doubleToAdd) { ((ParsedObjectContent)contentHolder).setData( new Double(doubleToAdd)); } - + } /** * <b><u>ParsedObjectContent</u></b><p> - * + * * ParsedObjectContent class. * Only be used locally in this object to parse event data more efficiently in the C. */ class ParsedObjectContent { private Object parsedData = null; - + public Object getData() { return parsedData; } - + public void setData(Object newData) { parsedData = newData; } diff --git a/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/JniTrace.java b/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/JniTrace.java index 86d91022a8..ca8cb07cfe 100644 --- a/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/JniTrace.java +++ b/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/JniTrace.java @@ -2,12 +2,12 @@ package org.eclipse.linuxtools.lttng.jni; /******************************************************************************* * Copyright (c) 2009, 2011 Ericsson, MontaVista Software - * + * * 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: * William Bourque (wbourque@gmail.com) - Initial API and implementation * Yufen Kuo (ykuo@mvista.com) - add support to allow user specify trace library path @@ -88,7 +88,7 @@ public abstract class JniTrace extends Jni_C_Common { // flag determine if live trace is supported or not // will be set to false in constructor if opening in live mode fails private boolean isLiveTraceSupported = true; - + // If traceLibPath is specified, it will be used to construct the complete path of the traceread library private String traceLibPath; @@ -157,30 +157,28 @@ public abstract class JniTrace extends Jni_C_Common { /** * Constructor that takes a tracepath parameter. * <p> - * + * * This constructor also opens the trace. - * - * @param newpath The <b>directory</b> of the trace to be opened - * - * @exception JniException + * + * @param newpath + * The <b>directory</b> of the trace to be opened */ - public JniTrace(String newpath) throws JniException { + public JniTrace(String newpath) { this(newpath, DEFAULT_LTT_DEBUG); } /** * Constructor that takes a tracepath parameter and a debug value. * <p> - * + * * This constructor also opens the trace. - * - * @param newpath The <b>directory</b> of the trace to be opened - * @param newPrintDebug Should the debug information be printed in the LTT C - * library - * - * @exception JniException + * + * @param newpath + * The <b>directory</b> of the trace to be opened + * @param newPrintDebug + * Should the debug information be printed in the LTT C library */ - public JniTrace(String newpath, boolean newPrintDebug) throws JniException { + public JniTrace(String newpath, boolean newPrintDebug) { tracepath = newpath; thisTracePtr = new Jni_C_Pointer_And_Library_Id(); printLttDebug = newPrintDebug; @@ -188,7 +186,7 @@ public abstract class JniTrace extends Jni_C_Common { /** * Copy constructor. - * + * * @param oldTrace A reference to the JniTrace to copy. */ public JniTrace(JniTrace oldTrace) { @@ -222,13 +220,15 @@ public abstract class JniTrace extends Jni_C_Common { /** * Constructor, using C pointer. * <p> - * - * @param newPtr The pointer to an already opened LttTrace C structure. - * @param newPrintDebug Should the debug information be printed in the LTT C - * library - * + * + * @param newPtr + * The pointer to an already opened LttTrace C structure. + * @param newPrintDebug + * Should the debug information be printed in the LTT C library + * * @exception JniException - * + * If the JNI call fails + * * @see org.eclipse.linuxtools.internal.lttng.jni.common.Jni_C_Pointer_And_Library_Id */ public JniTrace(Jni_C_Pointer_And_Library_Id newPtr, boolean newPrintDebug) throws JniException { @@ -253,13 +253,17 @@ public abstract class JniTrace extends Jni_C_Common { /** * Open an existing trace. * <p> - * + * * The tracepath is a directory and needs to exist, otherwise a * JniOpenTraceFailedException is throwed. - * - * @param newPath The <b>directory</b> of the trace to be opened - * - * @exception JniOpenTraceFailedException Thrown if the open failed + * + * @param newPath + * The <b>directory</b> of the trace to be opened + * @throws JniException + * If the JNI call fails + * + * @exception JniOpenTraceFailedException + * Thrown if the open failed */ public void openTrace(String newPath) throws JniException { // If open is called while a trace is already opened, we will try to @@ -276,10 +280,14 @@ public abstract class JniTrace extends Jni_C_Common { /** * Open an existing trace. * <p> - * + * * The tracepath should have been set already, - * - * @exception JniOpenTraceFailedException Thrown if the open failed + * + * @throws JniException + * If the JNI call fails + * + * @exception JniOpenTraceFailedException + * Thrown if the open failed */ public void openTrace() throws JniException { @@ -339,7 +347,7 @@ public abstract class JniTrace extends Jni_C_Common { /** * Close a trace. * <p> - * + * * If the trace is already closed, will silently do nothing. */ public void closeTrace() { @@ -363,7 +371,7 @@ public abstract class JniTrace extends Jni_C_Common { /** * This function force the library to free its memory. * <p> - * + * * Note : No call to the library will work after this until * ltt_initializeHandle is called again */ @@ -373,7 +381,7 @@ public abstract class JniTrace extends Jni_C_Common { /* * This function populates the trace data with data from LTT - * + * * @throws JniException */ private void populateTraceInformation() throws JniException { @@ -453,13 +461,13 @@ public abstract class JniTrace extends Jni_C_Common { /* * Fills a map of all the trace files. - * + * * Note: This function is called from C and there is no way to propagate * exception back to the caller without crashing JNI. Therefore, it MUST * catch all exceptions. - * + * * @param tracefileName - * + * * @param tracefilePtr */ protected void addTracefileFromC(String tracefileName, long tracefilePtr) { @@ -487,12 +495,12 @@ public abstract class JniTrace extends Jni_C_Common { * Return the top event in the events stack, determined by timestamp, in the * trace (all the tracefiles). * <p> - * + * * Note : If the events were read before, the top event and the event * currently loaded (currentEvent) are most likely the same. - * + * * @return The top event in the stack or null if no event is available or if the heap is null. - * + * * @see org.eclipse.linuxtools.lttng.jni.JniEvent */ public JniEvent findNextEvent() { @@ -506,9 +514,9 @@ public abstract class JniTrace extends Jni_C_Common { * Return the next event in the events stack, determined by timestamp, in * the trace (all the tracefiles). * <p> - * + * * @return The next event in the trace or null if no event is available. - * + * * @see org.eclipse.linuxtools.lttng.jni.JniEvent */ public JniEvent readNextEvent() { @@ -557,15 +565,15 @@ public abstract class JniTrace extends Jni_C_Common { /** * Read the next event on a certain tracefile. * <p> - * + * * By calling this function make sure the "global" readNextEvent() stay * synchronised. Calling readNextEvent() after this function will consider * this tracefile moved and is then consistent. - * + * * @param targetTracefile The tracefile object to read from - * + * * @return The next event in the tracefile or null if no event is available. - * + * * @see org.eclipse.linuxtools.lttng.jni.JniTracefile * @see org.eclipse.linuxtools.lttng.jni.JniEvent */ @@ -606,12 +614,12 @@ public abstract class JniTrace extends Jni_C_Common { /** * Seek to a certain time but <b>do not</b> read the next event. * <p> - * + * * This only position the trace, it will not return anything. * <p> - * + * * @param seekTime The time where we want to seek to - * + * * @see org.eclipse.linuxtools.internal.lttng.jni.common.JniTime */ public void seekToTime(JniTime seekTime) { @@ -635,13 +643,13 @@ public abstract class JniTrace extends Jni_C_Common { * Seek to a certain time on a certain tracefile but <b>do not</b> read the * next event. * <p> - * + * * This only position the trace, it will not return anything. * <p> - * + * * @param targetTracefile The tracefile object to read from * @param seekTime The time where we want to seek to - * + * * @see org.eclipse.linuxtools.lttng.jni.JniTracefile * @see org.eclipse.linuxtools.internal.lttng.jni.common.JniTime */ @@ -668,11 +676,11 @@ public abstract class JniTrace extends Jni_C_Common { * <p> * If no more events are available or an error happen, null will be * returned. - * + * * @param seekTime The time where we want to seek to. - * + * * @return The event just after the seeked time or null if none available. - * + * * @see org.eclipse.linuxtools.lttng.jni.JniEvent * @see org.eclipse.linuxtools.internal.lttng.jni.common.JniTime */ @@ -690,18 +698,18 @@ public abstract class JniTrace extends Jni_C_Common { * Seek to a certain timestamp on a certain tracefile and read the next * event. * <p> - * + * * If no more events are available or an error happen, null will be * returned. - * + * * Calling readNextEvent() after this function will consider this tracefile * moved and is then consistent.<br> - * + * * @param targetTracefile The tracefile object to read from * @param seekTime The time where we want to seek to - * + * * @return The event just after the seeked time or null if none available. - * + * * @see org.eclipse.linuxtools.lttng.jni.JniTracefile * @see org.eclipse.linuxtools.internal.lttng.jni.common.JniTime * @see org.eclipse.linuxtools.lttng.jni.JniEvent @@ -714,11 +722,11 @@ public abstract class JniTrace extends Jni_C_Common { /** * Get a certain tracefile from its given name. * <p> - * + * * @param tracefileName The name of the tracefile. - * + * * @return The tracefile found or null if none. - * + * * @see org.eclipse.linuxtools.lttng.jni.JniTracefile */ public JniTracefile requestTracefileByName(String tracefileName) { @@ -728,11 +736,11 @@ public abstract class JniTrace extends Jni_C_Common { /** * Get a certain event associated to a tracefile from the tracefile name. * <p> - * + * * @param tracefileName The name of the trace file. - * + * * @return Event of the tracefile or null if none found. - * + * * @see org.eclipse.linuxtools.lttng.jni.JniEvent */ public JniEvent requestEventByName(String tracefileName) { @@ -750,50 +758,111 @@ public abstract class JniTrace extends Jni_C_Common { } // Access to class variable. Most of them doesn't have setter + + /** + * Get the trace's path + * + * @return The trace path + */ public String getTracepath() { return tracepath; } + /** + * Get the CPU number + * + * @return The CPU number + */ public int getCpuNumber() { return cpuNumber; } + /** + * Get the type of architecture of this trace + * + * @return The value (as a long) for the architecture + */ public long getArchType() { return archType; } + /** + * Get the variant of the architecture of this trace + * + * @return The 'long' value, representing the architecture variant + */ public long getArchVariant() { return archVariant; } + /** + * Get the "size" of the architecture of this trace. Usually 32 or 64. + * + * @return The arch size + */ public short getArchSize() { return archSize; } + /** + * Get the major number of the LTT trace reading library's version. + * + * @return The major version number + */ public short getLttMajorVersion() { return lttMajorVersion; } + /** + * Get the minor number of the LTT trace reading library version. + * + * @return The minor version number + */ public short getLttMinorVersion() { return lttMinorVersion; } + /** + * Return if this trace was in flight recorder or not. + * + * @return The flight-recorder status value, as a short + */ public short getFlightRecorder() { return flightRecorder; } + /** + * Get the frequency scale of this trace. + * + * @return The frequency scale + */ public long getFreqScale() { return freqScale; } + /** + * Get the starting frequency of this trace. + * + * @return The start frequency + */ public long getStartFreq() { return startFreq; } + /** + * Get the current counter of the start time of this trace. + * + * @return The current start time counter + */ public long getStartTimestampCurrentCounter() { return startTimestampCurrentCounter; } + /** + * Get the start of this trace in monotonic time. + * + * @return The start timestamp + */ public long getStartMonotonic() { return startMonotonic; } @@ -801,7 +870,7 @@ public abstract class JniTrace extends Jni_C_Common { /** * Update trace file and file size information. * <p> - * + * * If the trace has any new events, fetch the new end time. */ public void updateTrace() { @@ -813,18 +882,38 @@ public abstract class JniTrace extends Jni_C_Common { } } + /** + * Get the start time of this trace. + * + * @return The start time, as a JniTime object + */ public JniTime getStartTime() { return startTime; } + /** + * Get the end time of this trace. + * + * @return The end time, as a JniTime object + */ public JniTime getEndTime() { return endTime; } + /** + * Get the start time with no adjustment + * + * @return The non-adjustement start time, as a JniTime + */ public JniTime getStartTimeNoAdjustement() { return startTimeNoAdjustement; } + /** + * Get the trace files of this trace directory. + * + * @return The map of the files + */ public HashMap<String, JniTracefile> getTracefilesMap() { return tracefilesMap; } @@ -832,11 +921,11 @@ public abstract class JniTrace extends Jni_C_Common { /** * The timestamp of the last read event. * <p> - * + * * Note : If no event is available, Long.MAX_VALUE is returned. - * + * * @return Time of the last event read - * + * * @see org.eclipse.linuxtools.internal.lttng.jni.common.JniTime */ public JniTime getCurrentEventTimestamp() { @@ -855,12 +944,12 @@ public abstract class JniTrace extends Jni_C_Common { /** * Pointer to the LttTrace C structure. * <p> - * + * * The pointer should only be used <u>INTERNALY</u>, do not use unless you * know what you are doing. - * + * * @return The actual (long converted) pointer or NULL. - * + * * @see org.eclipse.linuxtools.internal.lttng.jni.common.Jni_C_Pointer_And_Library_Id */ public Jni_C_Pointer_And_Library_Id getTracePtr() { @@ -869,7 +958,7 @@ public abstract class JniTrace extends Jni_C_Common { /** * Indicate whether a trace can be opened in live mode. - * + * * @return true if the trace version supports live */ public boolean isLiveTraceSupported() { @@ -879,9 +968,9 @@ public abstract class JniTrace extends Jni_C_Common { /** * Return boolean value saying if the debug is enabled in LTT or not. * <p> - * + * * Note : this need to be set at construction. - * + * * @return If the debug is set or not */ public boolean isPrintingLttDebug() { @@ -892,10 +981,10 @@ public abstract class JniTrace extends Jni_C_Common { * Print information for all the tracefiles associated with this trace. * <u>Intended to debug</u> * <p> - * + * * This function will call Ltt to print, so information printed will be the * one from the C structure, not the one populated in java. - * + * * @see org.eclipse.linuxtools.lttng.jni.JniTracefile */ public void printAllTracefilesInformation() { @@ -911,19 +1000,20 @@ public abstract class JniTrace extends Jni_C_Common { /** * Print information for this trace. <u>Intended to debug</u> * <p> - * + * * This function will call Ltt to print, so information printed will be the * one from the C structure, not the one populated in java. * <p> */ public void printTraceInformation() { - if (DEFAULT_LTT_DEBUG) + if (DEFAULT_LTT_DEBUG) { ltt_printTrace(thisTracePtr.getLibraryId(), thisTracePtr.getPointer()); + } } /** * toString() method. <u>Intended to debug</u><br> - * + * * @return Attributes of the object concatenated in String */ @Override @@ -972,25 +1062,25 @@ public abstract class JniTrace extends Jni_C_Common { * @return LTTng native trace library name */ public abstract String getTraceLibName(); - + /** * Function place holder to allocate a new JniTracefile. * <p> - * + * * JniTracefile constructor is non overridable so we need another * overridable function to return the correct version of JniTracefile.<br> * Effect of this function should be the same (allocate a fresh new * JniTracefile)<br> * <br> * <b>!! Override this with you version specific implementation.</b><br> - * + * * @param newPtr The pointer of an already opened LttTracefile C Structure * @param newParentTrace The JniTrace parent of this tracefile. - * + * * @return The newly allocated JniTracefile of the correct version - * + * * @throws JniException The construction (allocation) failed. - * + * * @see org.eclipse.linuxtools.lttng.jni.JniTracefile * @see org.eclipse.linuxtools.internal.lttng.jni.common.Jni_C_Pointer_And_Library_Id * @see org.eclipse.linuxtools.lttng.jni.JniTrace @@ -1015,9 +1105,9 @@ public abstract class JniTrace extends Jni_C_Common { /** * Initialize the C library. * <p> - * + * * Call the library loader with the .so we wish to load. - * + * * @return The library id if successful, -1 if something went wrong */ public int initializeLibrary() { @@ -1027,20 +1117,19 @@ public abstract class JniTrace extends Jni_C_Common { /** * Get the full trace library path. * <p> - * + * * Construct the full trace library path if traceLibPath is specified, * otherwise just the library name - * + * * @return The full trace library path */ public String getTraceLibFullPath() { - if (getTraceLibPath() == null) + if (getTraceLibPath() == null) { return getTraceLibName(); - else { - IPath path = new Path(getTraceLibPath()); - IPath traceLib = path.append(getTraceLibName()); - return traceLib.toOSString(); } + IPath path = new Path(getTraceLibPath()); + IPath traceLib = path.append(getTraceLibName()); + return traceLib.toOSString(); } } diff --git a/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/JniTracefile.java b/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/JniTracefile.java index e1545c747f..6b0fd24f03 100644 --- a/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/JniTracefile.java +++ b/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/JniTracefile.java @@ -1,12 +1,12 @@ package org.eclipse.linuxtools.lttng.jni; /******************************************************************************* * Copyright (c) 2009 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: * William Bourque (wbourque@gmail.com) - Initial API and implementation *******************************************************************************/ @@ -38,16 +38,16 @@ import org.eclipse.linuxtools.internal.lttng.jni.exception.JniTracefileWithoutEv * <b>NOTE</b><p> * This class is ABSTRACT, you need to extends it to support your specific LTTng version.<br> * Please look at the abstract functions to override at the bottom of this file.<p> - * + * */ -public abstract class JniTracefile extends Jni_C_Common +public abstract class JniTracefile extends Jni_C_Common { // Internal C pointer of the JniTracefile used in LTT private Jni_C_Pointer_And_Library_Id thisTracefilePtr = new Jni_C_Pointer_And_Library_Id(); - + // Reference to the parent trace private JniTrace parentTrace = null; - + // Data we should populate from LTT // Note that all type have been scaled up as there is no "unsigned" in java // This might be a problem about "unsigned long" as there is no equivalent in java @@ -58,12 +58,12 @@ public abstract class JniTracefile extends Jni_C_Common private long tid = 0; private long pgid = 0; private long creation = 0; - + // Internal C pointer for trace and marker // Note : These are real Jni_C_Pointer, not Jni_C_Pointer_And_Library_Id private Jni_C_Pointer tracePtr = null; private Jni_C_Pointer markerDataPtr = null; - + private int CFileDescriptor = 0; private long fileSize = 0; private long blocksNumber = 0; @@ -78,15 +78,15 @@ public abstract class JniTracefile extends Jni_C_Common private long eventsLost = 0; private long subBufferCorrupt = 0; private JniEvent currentEvent = null; - + // Internal C pointer for trace and marker // Note : This one is a real Jni_C_Pointer, not Jni_C_Pointer_And_Library_Id private Jni_C_Pointer bufferPtr = null; - + private long bufferSize = 0; // This map will hold markers_info owned by this tracefile - private HashMap<Integer, JniMarker> tracefileMarkersMap = null; + private HashMap<Integer, JniMarker> tracefileMarkersMap = null; // Native access functions protected native boolean ltt_getIsCpuOnline(int libId, long tracefilePtr); @@ -114,13 +114,13 @@ public abstract class JniTracefile extends Jni_C_Common protected native long ltt_getEventPtr(int libId, long tracefilePtr); protected native long ltt_getBufferPtr(int libId, long tracefilePtr); protected native long ltt_getBufferSize(int libId, long tracefilePtr); - + // Method to fill a map with marker object protected native void ltt_feedAllMarkers(int libId, long tracefilePtr); - + // Debug native function, ask LTT to print tracefile structure protected native void ltt_printTracefile(int libId, long tracefilePtr); - + /* * Default constructor is forbidden */ @@ -129,8 +129,8 @@ public abstract class JniTracefile extends Jni_C_Common /** * Copy constructor.<p> - * - * @param oldTracefile Reference to the JniTracefile you want to copy. + * + * @param oldTracefile Reference to the JniTracefile you want to copy. */ public JniTracefile(JniTracefile oldTracefile) { thisTracefilePtr = oldTracefile.thisTracefilePtr; @@ -164,13 +164,16 @@ public abstract class JniTracefile extends Jni_C_Common } /** - * Constructor, using C pointer.<p> - * - * @param newPtr The pointer of an already opened LttTracefile C Structure - * @param newParentTrace The JniTrace parent of this tracefile. - * + * Constructor, using C pointer. + * <p> + * + * @param newPtr + * The pointer of an already opened LttTracefile C Structure + * @param newParentTrace + * The JniTrace parent of this tracefile. * @exception JniException - * + * If the JNI call fails + * * @see org.eclipse.linuxtools.lttng.jni.JniTrace * @see org.eclipse.linuxtools.internal.lttng.jni.common.Jni_C_Pointer_And_Library_Id */ @@ -182,43 +185,43 @@ public abstract class JniTracefile extends Jni_C_Common // Retrieve the trace file information and load the first event. try { populateTracefileInformation(); - } + } catch (JniNoSuchEventException e) { throw new JniTracefileWithoutEventException("JniEvent constructor reported that no event of this type are usable. (Jni_Tracefile)"); //$NON-NLS-1$ } - } + } /** * Read the next event of this tracefile.<p> - * + * * Note : If the read succeed, the event will be populated.<p> - * + * * @return LTT read status, as defined in Jni_C_Constant - * + * * @see org.eclipse.linuxtools.internal.lttng.jni.common.Jni_C_Constant */ public int readNextEvent() { return currentEvent.readNextEvent(); - } + } /** * Seek to the given time.<p> - * + * * Note : If the seek succeed, the event will be populated. - * + * * @param seekTime The timestamp where to seek. - * + * * @return LTT read status, as defined in Jni_C_Constant - * + * * @see org.eclipse.linuxtools.internal.lttng.jni.common.Jni_C_Constant */ public int seekToTime(JniTime seekTime) { return currentEvent.seekToTime(seekTime); } - /* + /* * This function populates the tracefile data with data from LTT - * + * * @throws JniException */ private void populateTracefileInformation() throws JniException { @@ -256,17 +259,17 @@ public abstract class JniTracefile extends Jni_C_Common Jni_C_Pointer_And_Library_Id tmpEventPointer = new Jni_C_Pointer_And_Library_Id(thisTracefilePtr.getLibraryId(), ltt_getEventPtr(thisTracefilePtr.getLibraryId(), thisTracefilePtr.getPointer())); currentEvent = allocateNewJniEvent(tmpEventPointer , tracefileMarkersMap, this); - } - - /* + } + + /* * Fills a map of all the markers associated with this tracefile. - * + * * Note: This function is called from C and there is no way to propagate * exception back to the caller without crashing JNI. Therefore, it MUST * catch all exceptions. - * + * * @param markerId Id of the marker (int) - * @param markerInfoPtr C Pointer to a marker_info C structure + * @param markerInfoPtr C Pointer to a marker_info C structure */ private void addMarkersFromC(int markerId, long markerInfoPtr) { // Create a new tracefile object and insert it in the map @@ -279,108 +282,240 @@ public abstract class JniTracefile extends Jni_C_Common printlnC(thisTracefilePtr.getLibraryId(), "Failed to add marker to tracefileMarkersMap!(addMarkersFromC)\n\tException raised : " + e.toString()); //$NON-NLS-1$ } } - - // Access to class variable. Most of them doesn't have setter + + // Access to class variable. Most of them don't have setters + + /** + * Return if the CPU corresponding to this trace file is online or not. + * + * @return If the CPU is online, true/false + */ public boolean getIsCpuOnline() { return isCpuOnline; } - + + /** + * Get the complete path to this trace file + * + * @return The file path + */ public String getTracefilePath() { return tracefilePath; } + /** + * Get the base name of this trace file + * + * @return The file name + */ public String getTracefileName() { return tracefileName; } + /** + * Get the CPU number corresponding to this file + * + * @return The CPU number. Yes, as a long. Don't ask. + */ public long getCpuNumber() { return cpuNumber; } + /** + * Get the TID of this trace file (for UST traces) + * + * @return The TID + */ public long getTid() { return tid; } + /** + * Get the PGID of this trace file (for UST traces) + * + * @return The PGID + */ public long getPgid() { return pgid; } + /** + * Get the creation time of this process (for UST traces) + * + * @return The creation timestamp + */ public long getCreation() { return creation; } + /** + * Get the C pointer to the trace + * + * @return The Jni_C_Pointer to the trace + */ public Jni_C_Pointer getTracePtr() { return tracePtr; } + /** + * Get the C pointer to the marker data object + * + * @return The Jni_C_Pointer to the marker data + */ public Jni_C_Pointer getMarkerDataPtr() { return markerDataPtr; } + /** + * Get the file descriptor number used for this trace file + * + * @return The file descriptor index + */ public int getCFileDescriptor() { return CFileDescriptor; } + /** + * Get the size of this file, in bytes + * + * @return The file size + */ public long getFileSize() { return fileSize; } + /** + * Get the number of blocks in this trace file + * + * @return The number of blocks + */ public long getBlocksNumber() { return blocksNumber; } + /** + * Return if the byte order is reversed in this trace + * + * @return If the byte order is reversed, Y/N + */ public boolean getIsBytesOrderReversed() { return isBytesOrderReversed; } + /** + * Return if floats are aligned to words in this trace + * + * @return If floats are aligned, Y/N + */ public boolean getIsFloatWordOrdered() { return isFloatWordOrdered; } + /** + * Get the byte alignment of this trace + * + * @return The byte alignment + */ public long getAlignement() { return alignement; } + /** + * Get the size of the buffer headers, in bytes + * + * @return The buffer header size + */ public long getBufferHeaderSize() { return bufferHeaderSize; } + /** + * Get the number of bits for the current timestamp counter + * + * @return The number of bits for the TS counter + */ public int getBitsOfCurrentTimestampCounter() { return bitsOfCurrentTimestampCounter; } + /** + * Get the number of bits for the current event + * + * @return The number of bits for the event + */ public int getBitsOfEvent() { return bitsOfEvent; } + /** + * Get the mask for the current timestamp counter + * + * @return The TS counter mask + */ public long getCurrentTimestampCounterMask() { return currentTimestampCounterMask; } + /** + * Get the mask of the next bit for the current timestamp counter + * + * @return The mask of the next bit + */ public long getCurrentTimestampCounterMaskNextBit() { return currentTimestampCounterMaskNextBit; } + /** + * Get the amount of lost events in this trace file + * + * @return The amount of lost events + */ public long getEventsLost() { return eventsLost; } + /** + * Return if the current subbuffer is corrupted. Or maybe the number of + * corrupted subbuffers? I have no idea... + * + * @return The number of subbuffers + */ public long getSubBufferCorrupt() { return subBufferCorrupt; } + /** + * Get the current event this trace is pointed at. + * + * @return The current event, as a JniEvent + */ public JniEvent getCurrentEvent() { return currentEvent; } + /** + * Get a pointer to the current subbuffer + * + * @return Pointer to the current subbuffer + */ public Jni_C_Pointer getBufferPtr() { return bufferPtr; } + /** + * Get the buffer size for this trace, in bytes + * + * @return The buffer size + */ public long getBufferSize() { return bufferSize; } + /** + * Get the map of markers in this trace file + * + * @return The map of markers + */ public HashMap<Integer, JniMarker> getTracefileMarkersMap() { return tracefileMarkersMap; } @@ -389,49 +524,49 @@ public abstract class JniTracefile extends Jni_C_Common * Parent trace of this tracefile.<p> * * @return The parent trace - * + * * @see org.eclipse.linuxtools.lttng.jni.JniTrace */ public JniTrace getParentTrace() { return parentTrace; } - + /** * Pointer to the LttTracefile C structure<p> - * + * * The pointer should only be used <u>INTERNALY</u>, do not use unless you * know what you are doing.<p> - * + * * @return The actual (long converted) pointer or NULL. - * + * * @see org.eclipse.linuxtools.internal.lttng.jni.common.Jni_C_Pointer_And_Library_Id */ public Jni_C_Pointer_And_Library_Id getTracefilePtr() { return thisTracefilePtr; } - + /** - * Print information for this tracefile. + * Print information for this tracefile. * <u>Intended to debug</u><p> - * + * * This function will call Ltt to print, so information printed will be the * one from the C structure, not the one populated in java.<p> */ public void printTracefileInformation() { ltt_printTracefile(thisTracefilePtr.getLibraryId(), thisTracefilePtr.getPointer() ); } - + /** - * toString() method. + * toString() method. * <u>Intended to debug</u><p> - * + * * @return Attributes of the object concatenated in String */ @Override @SuppressWarnings("nls") public String toString() { String returnData = ""; - + returnData += "isCpuOnline : " + isCpuOnline + "\n"; returnData += "tracefilePath : " + tracefilePath + "\n"; returnData += "tracefileName : " + tracefileName + "\n"; @@ -461,13 +596,13 @@ public abstract class JniTracefile extends Jni_C_Common return returnData; } - - + + // **************************** // **** ABSTRACT FUNCTIONS **** // You MUST override those in your version specific implementation - - + + /** * Function place holder to allocate a new JniEvent.<p> * <br> @@ -475,23 +610,23 @@ public abstract class JniTracefile extends Jni_C_Common * Effect of this function should be the same (allocate a fresh new JniEvent).<br> * <br> * <b>!! Override this with you version specific implementation.</b><br> - * + * * @param newEventPtr The pointer of an already opened LttEvent C Structure * @param newMarkersMap An already populated HashMap of JniMarker objects for this new event * @param newParentTracefile The JniTrace parent of this tracefile. - * + * * @return The newly allocated JniEvent of the correct version - * + * * @throws JniException The construction (allocation) failed. - * + * * @see org.eclipse.linuxtools.lttng.jni.JniEvent * @see org.eclipse.linuxtools.internal.lttng.jni.common.Jni_C_Pointer_And_Library_Id * @see org.eclipse.linuxtools.lttng.jni.JniMarker * @see org.eclipse.linuxtools.lttng.jni.JniTracefile */ public abstract JniEvent allocateNewJniEvent(Jni_C_Pointer_And_Library_Id newEventPtr, HashMap<Integer, JniMarker> newMarkersMap, JniTracefile newParentTracefile) throws JniException; - - + + /** * Function place holder to allocate a new JniMarker.<p> * <br> @@ -499,16 +634,16 @@ public abstract class JniTracefile extends Jni_C_Common * Effect of this function should be the same (allocate a fresh new JniMarker).<br> * <br> * <b>!! Override this with you version specific implementation.</b><br> - * + * * @param newMarkerPtr The pointer of an already opened marker_info C Structure - * + * * @return The newly allocated JniMarker of the correct version - * + * * @throws JniException The construction (allocation) failed. - * + * * @see org.eclipse.linuxtools.lttng.jni.JniMarker * @see org.eclipse.linuxtools.internal.lttng.jni.common.Jni_C_Pointer_And_Library_Id */ public abstract JniMarker allocateNewJniMarker(Jni_C_Pointer_And_Library_Id newMarkerPtr) throws JniException; - + } diff --git a/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/Jni_C_Common.java b/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/Jni_C_Common.java index 901293da86..7eeb170828 100644 --- a/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/Jni_C_Common.java +++ b/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/Jni_C_Common.java @@ -4,12 +4,12 @@ import org.eclipse.linuxtools.internal.lttng.jni.common.Jni_C_Constant; /******************************************************************************* * Copyright (c) 2009 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: * William Bourque (wbourque@gmail.com) - Initial API and implementation *******************************************************************************/ @@ -19,40 +19,48 @@ import org.eclipse.linuxtools.internal.lttng.jni.common.Jni_C_Constant; * <b><u>Jni_C_Common</u></b> * <p> * Common constants and methods that should be shared between JNI objects. - * + * * <b>NOTE</b><p> * This class is ABSTRACT, and will be extended by each LTTng structure (Trac, Tracefile, Event, ...) - * + * */ -public abstract class Jni_C_Common extends Jni_C_Constant +public abstract class Jni_C_Common extends Jni_C_Constant { // Native console printing function protected native void ltt_printC(int libId, String string_to_print); - + /** - * Java-side console printing function.<p> - * - * Call the C printing function to make sure all printing happen on the same side. - * - * @param msg The string to print in C. + * Java-side console printing function. + * <p> + * + * Call the C printing function to make sure all printing happen on the same + * side. + * + * @param libId + * The ID of the trace-reading library + * @param msg + * The string to print in C. */ - @SuppressWarnings("nls") public void printC(int libId, String msg) { - // Need to escape "%" for C printf - msg = msg.replaceAll("%", "%%"); + // Need to escape "%" for C printf + msg = msg.replaceAll("%", "%%"); //$NON-NLS-1$ //$NON-NLS-2$ ltt_printC(libId, msg); } /** - * Java-side console printing function that add carriage return. <p> - * - * Call the C printing function to make sure all printing happen on the same side. - * - * @param msg The string to print in C. + * Java-side console printing function that add carriage return. + * <p> + * + * Call the C printing function to make sure all printing happen on the same + * side. + * + * @param libId + * The ID of the trace-reading library + * @param msg + * The string to print in C. */ - @SuppressWarnings("nls") public void printlnC(int libId, String msg) { - printC(libId, msg + "\n"); + printC(libId, msg + "\n"); //$NON-NLS-1$ } - + } diff --git a/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/factory/JniTraceFactory.java b/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/factory/JniTraceFactory.java index 6bbe622b64..8e17c8c4dc 100644 --- a/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/factory/JniTraceFactory.java +++ b/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/factory/JniTraceFactory.java @@ -1,12 +1,12 @@ package org.eclipse.linuxtools.lttng.jni.factory; /******************************************************************************* * Copyright (c) 2009, 2011 Ericsson, MontaVista Software - * + * * 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: * William Bourque (wbourque@gmail.com) - Initial API and implementation * Yufen Kuo (ykuo@mvista.com) - add support to allow user specify trace library path @@ -23,13 +23,13 @@ import org.eclipse.linuxtools.lttng.jni.JniTrace; * <b><u>JniTraceFactory</u></b> * <p> * This class factory is responsible of returning the correct JniTrace implementation from a (valid) trace path.<p> - * + * * The different version supported are listed below and the same version string are expected to be returned by JniTraceVersion.<br> * Each version need a different Lttv library so each need its liblttvtraceread-X.Y.so installed and available on the system. - * + * */ public class JniTraceFactory { - + // *** // Version string of the supported library version // These will be used in the switch below to find the correct version @@ -37,30 +37,38 @@ public class JniTraceFactory { static final String TraceVersion_v2_3 = "2.3"; //$NON-NLS-1$ static final String TraceVersion_v2_5 = "2.5"; //$NON-NLS-1$ static final String TraceVersion_v2_6 = "2.6"; //$NON-NLS-1$ - + /* * Default constructor is forbidden */ private JniTraceFactory(){ } - - /** - * Factory function : return the correct version of the JniTrace from a given path<p> - * NOTE : The correct Lttv library (liblttvtraceread-X.Y.so) need to be installed and accessible otherwise this - * function will return an Exception. - * - * If the path is wrong or if the library is not supported (bad version or missing library) an Exception will be throwed. - * - * @param path Path of the trace we want to open - * @param traceLibPath Directory to the trace libraries - * @param show_debug Should JniTrace print debug or not? - * - * @return a newly allocated JniTrace of the correct version - * - * @throws JniException - */ + + /** + * Factory function : return the correct version of the JniTrace from a + * given path + * <p> + * NOTE : The correct Lttv library (liblttvtraceread-X.Y.so) need to be + * installed and accessible otherwise this function will return an + * Exception. + * + * If the path is wrong or if the library is not supported (bad version or + * missing library) an Exception will be throwed. + * + * @param path + * Path of the trace we want to open + * @param traceLibPath + * Directory to the trace libraries + * @param show_debug + * Should JniTrace print debug or not? + * + * @return a newly allocated JniTrace of the correct version + * + * @throws JniException + * If the JNI call fails + */ static public JniTrace getJniTrace(String path, String traceLibPath, boolean show_debug) throws JniException { - + try { JniTraceVersion traceVersion = new JniTraceVersion(path, traceLibPath); JniTrace trace = null; @@ -72,18 +80,18 @@ public class JniTraceFactory { trace = new JniTrace_v2_3(path, show_debug); } if (trace != null) { - if (traceLibPath != null) + if (traceLibPath != null) { trace.setTraceLibPath(traceLibPath); + } trace.openTrace(path); return trace; - } else { - String errMsg = "Unrecognized/unsupported trace version\n\n" //$NON-NLS-1$ - + "Library reported trace version " + traceVersion.getVersionAsString() + "\n\n" //$NON-NLS-1$ //$NON-NLS-2$ - + "Make sure that you installed the corresponding parsing library (liblttvtraceread-" + traceVersion.getVersionAsString() + ".so) " //$NON-NLS-1$ //$NON-NLS-2$ - + "and that it can be found from either your LD_LIBRARY_PATH or the Trace Library Path (in LTTng project properties)\n\n" //$NON-NLS-1$ - + "Refer to the LTTng User Guide for more information"; //$NON-NLS-1$ - throw new JniException(errMsg); } + String errMsg = "Unrecognized/unsupported trace version\n\n" //$NON-NLS-1$ + + "Library reported trace version " + traceVersion.getVersionAsString() + "\n\n" //$NON-NLS-1$ //$NON-NLS-2$ + + "Make sure that you installed the corresponding parsing library (liblttvtraceread-" + traceVersion.getVersionAsString() + ".so) " //$NON-NLS-1$ //$NON-NLS-2$ + + "and that it can be found from either your LD_LIBRARY_PATH or the Trace Library Path (in LTTng project properties)\n\n" //$NON-NLS-1$ + + "Refer to the LTTng User Guide for more information"; //$NON-NLS-1$ + throw new JniException(errMsg); } catch (JniTraceVersionException e) { String errMsg = "Couldn't obtain the trace version\n\n" //$NON-NLS-1$ @@ -94,5 +102,5 @@ public class JniTraceFactory { throw new JniException(errMsg); } } - + } diff --git a/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/factory/JniTraceVersion.java b/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/factory/JniTraceVersion.java index 6b9f7bc327..acbe25cfe1 100644 --- a/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/factory/JniTraceVersion.java +++ b/lttng/org.eclipse.linuxtools.lttng.jni/src/org/eclipse/linuxtools/lttng/jni/factory/JniTraceVersion.java @@ -1,12 +1,12 @@ package org.eclipse.linuxtools.lttng.jni.factory; /******************************************************************************* * Copyright (c) 2009, 2011 Ericsson, MontaVista Software - * + * * 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: * William Bourque (wbourque@gmail.com) - Initial API and implementation * Yufen Kuo (ykuo@mvista.com) - add support to allow user specify trace library path @@ -14,121 +14,135 @@ package org.eclipse.linuxtools.lttng.jni.factory; import java.io.File; -import org.eclipse.linuxtools.internal.lttng.jni.exception.JniException; import org.eclipse.linuxtools.internal.lttng.jni.exception.JniTraceVersionException; /** * <b><u>JniTraceVersion</u></b> * <p> * This class is responsible of returning the correct version number of a trace at a certain given path.<p> - * + * * The class will call the C library to get the correct version number from the trace.<p> - * + * * Lttv library loader (liblttvtraceread_loader.so) and the default Lttv library (liblttvtraceread.so) must be installed on system and available to java. - * + * */ public class JniTraceVersion { - + private static final String LTTVTRACEREAD_LOADER_LIBNAME = "lttvtraceread_loader"; //$NON-NLS-1$ // Native access functions protected native void ltt_getTraceVersion(String tracepath); - + // Variables to store version number private int majorNumber = 0; private int minorNumber = 0; - + // To store the given tracepath private String tracepath = ""; //$NON-NLS-1$ // To store the given trace lib path private String traceLibPath = ""; //$NON-NLS-1$ - + // Was the trace read already? private boolean wasTraceRead = false; - + /** * Default constructor.<p> - * + * * Do nothing, readVersionFromTrace(path) will need to be called by the user */ public JniTraceVersion() { - // Nothing to do + // Nothing to do } - - /** - * Constructor that takes a tracepath parameter.<p> - * - * This constructor read the version number from the trace, so it might throw. - * - * @param newTracepath The <b>directory</b> of the trace to read. - * @param traceLibPath The <b>directory</b> of the trace libraries. - * - * @exception JniException If the library can not be loaded,if the path is wrong or if something go wrong during the read. + + /** + * Constructor that takes a tracepath parameter. + * <p> + * + * This constructor read the version number from the trace, so it might + * throw. + * + * @param newTracepath + * The <b>directory</b> of the trace to read. + * @param traceLibPath + * The <b>directory</b> of the trace libraries. + * + * @exception JniTraceVersionException + * If the library can not be loaded,if the path is wrong or + * if something go wrong during the read. */ public JniTraceVersion(String newTracepath, String traceLibPath) throws JniTraceVersionException { - // Read the version number from the trace + // Read the version number from the trace readVersionFromTrace(newTracepath, traceLibPath); } - + /** * Copy constructor. - * - * @param oldVersion A reference to the JniTraceVersion to copy. + * + * @param oldVersion A reference to the JniTraceVersion to copy. */ public JniTraceVersion(JniTraceVersion oldVersion) { majorNumber = oldVersion.majorNumber; minorNumber = oldVersion.minorNumber; } - + /* * Read the version from the (already set) tracepath.<p> - * + * * This version is used internally and will silently dismiss any exceptions. - * + * */ private void readVersionNumberNofail() { try { readVersionFromTrace(tracepath, traceLibPath); } - catch(JniTraceVersionException e) { + catch(JniTraceVersionException e) { // Yes, we do ignore exception. } } - - /** - * Read the version from the (already set) tracepath.<p> - * - * This function throw if the library can not be loaded, if the path is wrong or if something go wrong during the read. - * - */ + + /** + * Read the version from the (already set) trace path. + * <p> + * + * @throws JniTraceVersionException + * If the library can not be loaded, if the path is wrong or if + * something go wrong during the read. + * + */ public void readVersionNumber() throws JniTraceVersionException { readVersionFromTrace(tracepath, traceLibPath); } - - /** - * Read the version from a given tracepath.<p> - * MajorVersion and MinorVersion should be set after a successful execution of this function.<br> - * - * This function throw if the library can not be loaded,if the path is wrong or if something go wrong during the read. - * - */ + + /** + * Read the version from a given tracepath. + * <p> + * MajorVersion and MinorVersion should be set after a successful execution + * of this function.<br> + * + * @param newTracepath + * The path of the new trace + * @param newTraceLibPath + * The path to the trace reading library to use + * @throws JniTraceVersionException + * If the library can not be loaded,if the path is wrong or if + * something go wrong during the read. + * + */ public void readVersionFromTrace(String newTracepath, String newTraceLibPath) throws JniTraceVersionException { - + // Verify that the tracepath isn't obliviously wrong (null or empty) if ( (newTracepath == null) || (newTracepath.equals("") ) ) { //$NON-NLS-1$ throw new JniTraceVersionException("ERROR : Tracepath is null or empty! (readVersionNumber)"); //$NON-NLS-1$ } - else { - // Otherwise set the path in case it was changed - tracepath = newTracepath; - } + // Otherwise set the path in case it was changed + tracepath = newTracepath; traceLibPath = newTraceLibPath; - + try { if (newTraceLibPath == null || newTraceLibPath.isEmpty()) { // Load the C library here. // If LD_LIBRARY_PATH is not set correctly this will raise a java.lang.UnsatisfiedLinkError - System.loadLibrary(LTTVTRACEREAD_LOADER_LIBNAME); + System.loadLibrary(LTTVTRACEREAD_LOADER_LIBNAME); } else { File loaderLib = new File(newTraceLibPath, System.mapLibraryName(LTTVTRACEREAD_LOADER_LIBNAME)); System.load(loaderLib.getCanonicalPath()); @@ -139,87 +153,87 @@ public class JniTraceVersion { // We can now assume that the trace was read wasTraceRead = true; } - // The library was unable to load -> Lttv not installed or bad version of it? + // The library was unable to load -> Lttv not installed or bad version of it? catch (java.lang.UnsatisfiedLinkError e) { throw new JniTraceVersionException("\nERROR : Could not get trace version. Is the library missing?" + //$NON-NLS-1$ "\nMake sure your \"LD_LIBRARY_PATH\" is setted correctly (readVersionNumber)\n"); //$NON-NLS-1$ } - // Something else failed -> Possibly a bad tracepath was given + // Something else failed -> Possibly a bad tracepath was given catch (Exception e) { throw new JniTraceVersionException("\nERROR : Call to ltt_getTraceVersion failed. (readVersionNumber)\n"); //$NON-NLS-1$ } } - + /** * Get major version number of the trace.<p> * Note : readVersionFromTrace() will be called if it wasn't done but exception will be silently ignored. - * + * * @return major version */ public int getMajor() { if ( wasTraceRead == false ) { readVersionNumberNofail(); } - + return majorNumber; } - + /** * Get minor version number of the trace.<p> * Note : readVersionFromTrace() will be called if it wasn't done but exception will be silently ignored. - * + * * @return minor version */ public int getMinor() { if ( wasTraceRead == false ) { readVersionNumberNofail(); } - + return minorNumber; } - + /** * Get full version number of the trace.<p> * Note : readVersionFromTrace() will be called if it wasn't done but exception will be silently ignored. - * + * * @return Full Version as float */ public float getVersionAsFloat() { if ( wasTraceRead == false ) { readVersionNumberNofail(); } - - return ((float)majorNumber + ((float)minorNumber)/10); + + return (majorNumber + ((float)minorNumber)/10); } - + /** * Get full version number of the trace.<p> * Note : readVersionFromTrace() will be called if it wasn't done but exception will be silently ignored. - * + * * @return Full Version as string */ public String getVersionAsString() { if ( wasTraceRead == false ) { readVersionNumberNofail(); } - + return majorNumber + "." + minorNumber; //$NON-NLS-1$ } - + /** * Get for the current tracepath - * + * * @return The tracepath was are currently using. */ public String getTracepath() { return tracepath; } - + /** * Set for the tracepath.<p> * NOTE : Changing this will reset the version number currently loaded. * NOTE2 : readVersionFromTrace() will be called but exception will be silently ignored. - * + * * @param newtracepath The net tracepath */ public void setTracepath(String newtracepath) { @@ -227,11 +241,11 @@ public class JniTraceVersion { minorNumber = 0; wasTraceRead = false; tracepath = newtracepath; - + // Call the read function. This will fill up all the number if it goes well. readVersionNumberNofail(); } - + /* * This function is be called from the C side to assign the version number the Java variable. */ @@ -239,12 +253,12 @@ public class JniTraceVersion { majorNumber = newMajor; minorNumber = newMinor; } - - + + @Override @SuppressWarnings("nls") public String toString() { return "JniTraceVersion [" + majorNumber + "." + minorNumber + "]"; } - + } |