Update of /cvsroot/javaprofiler/library/src2 In directory usw-pr-cvs1:/tmp/cvs-serv6750/src2 Modified Files: BAD_COMMAND_Exception.java BAD_DATA_TYPE_Exception.java BAD_INFO_ID_Exception.java BAD_INFO_TYPE_Exception.java BAD_OBJ_ID_Exception.java Buffer.java COMMUN_Exception.java Commun.java CommunSetup.java CommunSetupShMem.java CommunSetupSocket.java CommunShMem.java CommunSocket.java IProf.java IProfException.java UNKNOWN_Exception.java Log Message: documentation to IProf interface added Index: BAD_COMMAND_Exception.java =================================================================== RCS file: /cvsroot/javaprofiler/library/src2/BAD_COMMAND_Exception.java,v retrieving revision 1.2 retrieving revision 1.3 diff -C2 -r1.2 -r1.3 *** BAD_COMMAND_Exception.java 2001/09/02 20:14:22 1.2 --- BAD_COMMAND_Exception.java 2001/09/23 16:50:15 1.3 *************** *** 33,35 **** --- 33,42 ---- */ + /** Bad command exception. This exception is raised when a request for + ** specified objID is not possible (eg. when you try (in one call to + ** getAll() or getChanged()) to gain threads where concrete method was + ** called and you have method's objId only). + ** + ** @author Marek Przeczek */ + public class BAD_COMMAND_Exception extends IProfException {}; Index: BAD_DATA_TYPE_Exception.java =================================================================== RCS file: /cvsroot/javaprofiler/library/src2/BAD_DATA_TYPE_Exception.java,v retrieving revision 1.2 retrieving revision 1.3 diff -C2 -r1.2 -r1.3 *** BAD_DATA_TYPE_Exception.java 2001/09/02 20:14:22 1.2 --- BAD_DATA_TYPE_Exception.java 2001/09/23 16:50:15 1.3 *************** *** 33,35 **** --- 33,44 ---- */ + /** Bad objID type exception. This exception is raised when used ID is + ** of different type than specified (eg. when an object has statistic + ** data about memory profiling only and someone tries to gain cpu + ** profiling data from it). + ** + ** @see BAD_INFO_TYPE_Exception + ** + ** @author Marek Przeczek */ + public class BAD_DATA_TYPE_Exception extends IProfException {}; Index: BAD_INFO_ID_Exception.java =================================================================== RCS file: /cvsroot/javaprofiler/library/src2/BAD_INFO_ID_Exception.java,v retrieving revision 1.2 retrieving revision 1.3 diff -C2 -r1.2 -r1.3 *** BAD_INFO_ID_Exception.java 2001/09/02 20:14:22 1.2 --- BAD_INFO_ID_Exception.java 2001/09/23 16:50:15 1.3 *************** *** 33,35 **** --- 33,43 ---- */ + /** Bad infoID exception. This exception is raised when used ID is not + ** an infoID of an object (eg. when objID is used as an infoID, this + ** exception can be raised). + ** + ** @see BAD_OBJ_ID_Exception + ** + ** @author Marek Przeczek */ + public class BAD_INFO_ID_Exception extends IProfException {}; Index: BAD_INFO_TYPE_Exception.java =================================================================== RCS file: /cvsroot/javaprofiler/library/src2/BAD_INFO_TYPE_Exception.java,v retrieving revision 1.2 retrieving revision 1.3 diff -C2 -r1.2 -r1.3 *** BAD_INFO_TYPE_Exception.java 2001/09/02 20:14:22 1.2 --- BAD_INFO_TYPE_Exception.java 2001/09/23 16:50:15 1.3 *************** *** 33,35 **** --- 33,49 ---- */ + /** Bad infoID type exception. This exception is raised when type of + ** infoID is bad (eg. infoID exists but is of different type than + ** specified). + ** + ** An example: when trying to gain information about method (eg. with + ** infoId = 1), getInfo( 1, METHOD_INFO) must be called. METHOD_INFO + ** specifies the type of information, in this case information about + ** method. If another info type is specified, BAD_INFO_TYPE_Exception + ** will be raised. + ** + ** @see BAD_DATA_TYPE_Exception + ** + ** @author Marek Przeczek */ + public class BAD_INFO_TYPE_Exception extends IProfException {}; Index: BAD_OBJ_ID_Exception.java =================================================================== RCS file: /cvsroot/javaprofiler/library/src2/BAD_OBJ_ID_Exception.java,v retrieving revision 1.2 retrieving revision 1.3 diff -C2 -r1.2 -r1.3 *** BAD_OBJ_ID_Exception.java 2001/09/02 20:14:22 1.2 --- BAD_OBJ_ID_Exception.java 2001/09/23 16:50:15 1.3 *************** *** 33,35 **** --- 33,43 ---- */ + /** Bad objectID exception. This exception is raised when used ID is not + ** an objID of an object (eg. when an ID to which no object exists is + ** used, this exception is raised). + ** + ** @see BAD_INFO_ID_Exception + ** + ** @author Marek Przeczek */ + public class BAD_OBJ_ID_Exception extends IProfException {}; Index: Buffer.java =================================================================== RCS file: /cvsroot/javaprofiler/library/src2/Buffer.java,v retrieving revision 1.4 retrieving revision 1.5 diff -C2 -r1.4 -r1.5 *** Buffer.java 2001/09/02 20:14:22 1.4 --- Buffer.java 2001/09/23 16:50:15 1.5 *************** *** 33,42 **** --- 33,55 ---- */ + /** I/O buffer. This class implements an input/output buffer + ** needed during communication between profiler dynamic library + ** and Java. Same class (of the same name and functionality) exists + ** in the dynamic library side - but it is more complicated and flexible + ** than this one. + ** + ** @see Commun + ** + ** @author Marek Przeczek */ + public class Buffer { + /// internal buffer private byte[] _buf; + /// size of buffer private int _size; + /// Default constructor. public Buffer() { *************** *** 45,48 **** --- 58,68 ---- } + /** Constructor. This constructor constructs Buffer object using data + ** from another buffer. The data are copied to this newly created + ** Buffer object. + ** + ** @param buf buffer (an array of bytes) + ** @param size size of buffer 'buf' */ + public Buffer( byte[] buf, int size) { *************** *** 53,56 **** --- 73,83 ---- } + /** Use existing buffer. This method replaces internal buffer by + ** the given one. No copy is created, the buffer 'buf' is used as + ** an internal buffer. + ** + ** @param buf buffer (an array of bytes) + ** @param size size of buffer 'buf' */ + public Buffer useBuffer( byte[] buf, int size) { *************** *** 60,68 **** return this; } ! public byte[] getBuffer() { return _buf;} public int getSize() { return _size;} public void clear() { --- 87,108 ---- return this; } ! ! /** Get buffer. This method returns a reference ! ** to buffer data. ! ** ! ** @return reference to buffer */ ! public byte[] getBuffer() { return _buf;} + /** Get size of data. This method returns size + ** of data stored in buffer. + ** + ** @return size of data */ + public int getSize() { return _size;} + /** Clear buffer. It truncates buffer to zero length, + ** everything stored in the buffer will be lost. */ + public void clear() { *************** *** 71,74 **** --- 111,123 ---- } + /** Put integer into buffer. By this method you can insert Java + ** integer into buffer (of bytes). + ** + ** @param c integer + ** + ** @return this Buffer object + ** + ** @see getInt(), getLong(), getString() */ + public Buffer putInt( int c) { *************** *** 85,88 **** --- 134,146 ---- } + /** Get integer from buffer. This method grabs Java integer located + ** at position 'offset' from the buffer. + ** + ** @param offset position in the buffer + ** + ** @return grabbed integer + ** + ** @see putInt(), getLong(), getString() */ + public int getInt( int offset) { *************** *** 99,102 **** --- 157,169 ---- } + /** Get long integer from buffer. This method grabs Java long + ** integer located at position 'offset' from the buffer. + ** + ** @param offset position in the buffer + ** + ** @return grabbed long integer + ** + ** @see putInt(), getInt(), getString() */ + public long getLong( int offset) { *************** *** 107,110 **** --- 174,187 ---- } + /** Get string from buffer. This method grabs Java string located + ** at position 'offset' from the buffer. In the buffer string is + ** stored as C string (text + terminating null). + ** + ** @param offset position in the buffer + ** + ** @return grabbed string + ** + ** @see putInt(), getInt(), getLong() */ + public String getString( int offset) { *************** *** 114,118 **** return new String( _buf, offset, pos-offset); } ! private byte[] copyBuffer( byte[] dest, byte[] src, int sz) { --- 191,205 ---- return new String( _buf, offset, pos-offset); } ! ! /** Copy buffer. It only copies source buffer to destination one. ! ** Destination buffer must be of sufficient size, no check is ! ** done. ! ** ! ** @param dest destination ! ** @param src source ! ** @param sz size of source buffer ! ** ! ** @return reference to destination buffer */ ! private byte[] copyBuffer( byte[] dest, byte[] src, int sz) { Index: COMMUN_Exception.java =================================================================== RCS file: /cvsroot/javaprofiler/library/src2/COMMUN_Exception.java,v retrieving revision 1.2 retrieving revision 1.3 diff -C2 -r1.2 -r1.3 *** COMMUN_Exception.java 2001/09/02 20:14:22 1.2 --- COMMUN_Exception.java 2001/09/23 16:50:15 1.3 *************** *** 33,35 **** --- 33,40 ---- */ + /** Exception. This exception is raised when a communication failed + ** (eg. when server falls down during communication). + ** + ** @author Marek Przeczek */ + public class COMMUN_Exception extends IProfException {}; Index: Commun.java =================================================================== RCS file: /cvsroot/javaprofiler/library/src2/Commun.java,v retrieving revision 1.2 retrieving revision 1.3 diff -C2 -r1.2 -r1.3 *** Commun.java 2001/09/02 20:14:22 1.2 --- Commun.java 2001/09/23 16:50:15 1.3 *************** *** 33,46 **** --- 33,88 ---- */ + /** Communication. This is a standard interface for all communication + ** classes. Whole communication is done thru an instance of this + ** interface implementation. + ** + ** @see CommunSocket, CommunShMem + ** + ** @author Marek Przeczek */ + public interface Commun { + /** Initialization of communication. This method should + ** initialize the communication, it means to make a connection + ** with opposite side. + ** + ** @return false (failed); + ** true (ok, initialized) */ + public boolean initialize(); + /** Read data. This method is used to read data + ** from communication channel (socket, shmem etc.) to buffer. + ** + ** @param b reference to Buffer object + ** + ** @return reference to this Commun object + ** + ** @see write() */ + public Commun read( Buffer b); + /** Write data. This method is used to write data + ** from buffer to communication channel (socket, shmem etc.). + ** + ** @param b reference to Buffer object + ** + ** @return reference to this Commun object + ** + ** @see read() */ + public Commun write( Buffer b); + /** Failure indication. Use this method if you want to know + ** the last operation was successful or not. + ** + ** @return false (last operation was successful); + ** true (last operation failed) */ + public boolean hasFailed(); + /** Stop communication. Is stops communication and closes + ** communication channel. */ + public void stopCommun(); }; Index: CommunSetup.java =================================================================== RCS file: /cvsroot/javaprofiler/library/src2/CommunSetup.java,v retrieving revision 1.2 retrieving revision 1.3 diff -C2 -r1.2 -r1.3 *** CommunSetup.java 2001/09/02 20:14:22 1.2 --- CommunSetup.java 2001/09/23 16:50:15 1.3 *************** *** 33,45 **** */ public abstract class CommunSetup { public static final int COMMUN_SOCKET = 0; public static final int COMMUN_SHMEM = 1; - public int communType; public CommunSetup() { --- 33,55 ---- */ + /** Communication setup. Other classes holding setup data are inherited + ** from this abstract class. + ** + ** @see CommunSetupSocket, CommunSetupShMem + ** + ** @author Marek Przeczek */ + public abstract class CommunSetup { + /// type of communication - sockets public static final int COMMUN_SOCKET = 0; + /// type of communication - shared memory public static final int COMMUN_SHMEM = 1; + /// type of communication public int communType; + /** Default constructor. Socket communication is used by default. */ public CommunSetup() { *************** *** 48,53 **** } public CommunSetup( int communType) { ! this.communType = communType; } --- 58,69 ---- } + /** Constructor. It sets type of communication. + ** 'communType' argument can take one of the following values: + ** #COMMUN_SOCKET or #COMMUN_SHMEM. + ** + ** @param communType type of communication */ + public CommunSetup( int communType) { ! this.communType = communType; } Index: CommunSetupShMem.java =================================================================== RCS file: /cvsroot/javaprofiler/library/src2/CommunSetupShMem.java,v retrieving revision 1.2 retrieving revision 1.3 diff -C2 -r1.2 -r1.3 *** CommunSetupShMem.java 2001/09/02 20:14:22 1.2 --- CommunSetupShMem.java 2001/09/23 16:50:15 1.3 *************** *** 33,43 **** */ public class CommunSetupShMem extends CommunSetup { public String shmemId = new String( "com"); public int shmemSize = 256*1024; - public CommunSetupShMem() { --- 33,52 ---- */ + /** Shared memory communication setup. This class contains setup data + ** for shared memory communication. + ** + ** @see CommunSetup, CommunSetupSocket + ** + ** @author Marek Przeczek */ + public class CommunSetupShMem extends CommunSetup { + /// shared memory name (identifier) - 3 characters public String shmemId = new String( "com"); + /// shared memory size - in bytes public int shmemSize = 256*1024; + /// Default constructor. public CommunSetupShMem() { *************** *** 45,48 **** --- 54,62 ---- } + /** Constructor. It takes setup from given parameters. + ** + ** @param shmemId shared memory name (identifier) - 3 chars only ! + ** @param shmemSize shared memory size - in bytes */ + public CommunSetupShMem( String shmemId, int shmemSize) { Index: CommunSetupSocket.java =================================================================== RCS file: /cvsroot/javaprofiler/library/src2/CommunSetupSocket.java,v retrieving revision 1.3 retrieving revision 1.4 diff -C2 -r1.3 -r1.4 *** CommunSetupSocket.java 2001/09/02 20:14:22 1.3 --- CommunSetupSocket.java 2001/09/23 16:50:15 1.4 *************** *** 33,54 **** */ public class CommunSetupSocket extends CommunSetup { public static final int SERVER_MODE = 0; public static final int CLIENT_MODE = 1; - public int connectMode = CLIENT_MODE; public String hostname = new String( "127.0.0.1"); public int port = 25595; ! public CommunSetupSocket() { super( COMMUN_SOCKET); } public CommunSetupSocket( int connectMode, String hostname, int port) { --- 33,71 ---- */ + /** Socket communication setup. This class contains setup data + ** for socket communication. + ** + ** @see CommunSetup, CommunSetupShMem */ + public class CommunSetupSocket extends CommunSetup { + /// connect mode - server public static final int SERVER_MODE = 0; + /// connect mode - client public static final int CLIENT_MODE = 1; + /// connect mode (client by default) public int connectMode = CLIENT_MODE; + /// hostname (used when connect mode is set to 'client') public String hostname = new String( "127.0.0.1"); + /// TCP port (where server should listen or where client should connect to) public int port = 25595; ! /// Default constructor. public CommunSetupSocket() { super( COMMUN_SOCKET); } + + /** Constructor. It takes setup from given parameters. + ** 'connectMode' argument can take one of the following values: + ** #SERVER_MODE or #CLIENT_MODE. + ** + ** @param connectMode connect mode + ** @param hostname hostname + ** @param port port */ public CommunSetupSocket( int connectMode, String hostname, int port) { Index: CommunShMem.java =================================================================== RCS file: /cvsroot/javaprofiler/library/src2/CommunShMem.java,v retrieving revision 1.4 retrieving revision 1.5 diff -C2 -r1.4 -r1.5 *** CommunShMem.java 2001/09/02 20:14:22 1.4 --- CommunShMem.java 2001/09/23 16:50:15 1.5 *************** *** 33,58 **** */ public class CommunShMem implements Commun { private long data = 0; public CommunShMem( String shmemId, int shmemSize) { construct( shmemId, shmemSize);} ! private native void construct( String shmemId, int shmemSize); protected native void finalize(); ! ! public boolean initialize() { return true;} public native Commun read( Buffer b); public native Commun write( Buffer b); public native boolean hasFailed(); public native void stopCommun(); static { --- 33,123 ---- */ + /** Shared memory communication. This class implements shared memory + ** communication and offers the user of this class the standard + ** communication interface. Implementation is system dependent + ** (so it is different on WIN32 and UNIX systems). It should be + ** faster then using sockets. Because Java has no support for shared + ** memory, JNI is used. + ** + ** @see CommunSocket, Commun + ** + ** @author Marek Przeczek */ + public class CommunShMem implements Commun { + /// 8 bytes long pointer to data private long data = 0; + /** Constructor. Creates shared memory block and + ** needed semaphores for communication. If semaphores + ** or shared memory block already exist, they are used. + ** + ** @param shmemId shared memory identifier (3 characters long only) + ** @param shmemSize shared memory size + ** + ** @see construct() */ public CommunShMem( String shmemId, int shmemSize) { construct( shmemId, shmemSize);} ! /** Constructor. Because JNI does not allow native constructors, ! ** this native method picks constructor's function over. ! ** ! ** @param shmemId shared memory identifier (3 characters long only) ! ** @param shmemSize shared memory size ! ** ! ** @see CommunShMem() */ + private native void construct( String shmemId, int shmemSize); + + /** Finalize. It deattaches and destroys shared memory, destroys + ** semaphores. See Java Language Reference for more information. */ + protected native void finalize(); ! ! /** Initialization of communication. This method does nothing, ! ** it always returns true. ! ** ! ** @return true (ok, initialized) */ ! public boolean initialize() { return true;} + /** Read data. This method is used to read data + ** from communication channel (shmem) to buffer. + ** + ** @param b reference to Buffer object + ** + ** @return reference to this Commun object + ** + ** @see write() */ + public native Commun read( Buffer b); + /** Write data. This method is used to write data + ** from buffer to communication channel (shmem). + ** + ** @param b reference to Buffer object + ** + ** @return reference to this Commun object + ** + ** @see write() */ + public native Commun write( Buffer b); + /** Failure indication. Use this method if you want to know + ** the last operation was successful or not. + ** + ** @return false (last operation was successful); + ** true (last operation failed) */ + public native boolean hasFailed(); + + /** Stop shared memory communication. It stops communication, + ** locks/unlocks semaphores and leaves them in consistent state. */ public native void stopCommun(); + /** Static initializer. It loads native class (stored in dynamic + ** library) to the memory. */ + static { Index: CommunSocket.java =================================================================== RCS file: /cvsroot/javaprofiler/library/src2/CommunSocket.java,v retrieving revision 1.6 retrieving revision 1.7 diff -C2 -r1.6 -r1.7 *** CommunSocket.java 2001/09/02 20:14:22 1.6 --- CommunSocket.java 2001/09/23 16:50:15 1.7 *************** *** 37,59 **** import java.net.*; public class CommunSocket implements Commun { private int _connectMode; private String _host; private int _port; ! private boolean _failed = false; private Socket _sock; private BufferedInputStream _in; private BufferedOutputStream _out; private Buffer _buf = (new Buffer()).useBuffer( new byte[4], 4); public CommunSocket( int connectMode, String host, int port) { --- 37,88 ---- import java.net.*; + /** Socket communication. This class implements TCP/IP socket + ** communication and offers the user of this class the standard + ** communication interface.This class stands a server or client out. + ** + ** @see CommunShMem, Commun + ** + ** @author Marek Przeczek */ + public class CommunSocket implements Commun { + /// connect mode (0 = server, 1 = client) private int _connectMode; + /** Hostname. It is used only when connectMode is set + ** to 'client' (1); it contains target host's name. */ + private String _host; + /** Port number. When connectMode is set to 'server' (0), + ** it contains port number, where server listens for new + ** connections; when connectMode is set to 'client' (1), + ** it contains target host's port number. */ + private int _port; ! /// failure indicator private boolean _failed = false; + /// socket private Socket _sock; + /// input stream private BufferedInputStream _in; + /// output stream private BufferedOutputStream _out; + /// internal buffer for binary data private Buffer _buf = (new Buffer()).useBuffer( new byte[4], 4); + /** Constructor. It initializes server for listening + ** on given port (if connectMode is set to 'server'). + ** If connectMode is set to 'client', this class connects + ** to the target specified by 'host' and 'port' arguments. + ** + ** @param connectMode mode (0 = as server, 1 = as client) + ** @param host target host (if connectMode is set to 'client') + ** @param port port number */ public CommunSocket( int connectMode, String host, int port) { *************** *** 64,67 **** --- 93,105 ---- } + /** Initialization of communication. This method initializes + ** socket communication - waits for client and makes a connection. + ** Once a client is connected to this server, another client + ** has no possibility to connect. If used in client mode, it tries + ** to connect to server. + ** + ** @return false (failed); + ** true (ok, client connected) */ + public boolean initialize() { *************** *** 88,91 **** --- 126,138 ---- } + /** Read data. This method is used to read data + ** from communication channel (socket) to buffer. + ** + ** @param b reference to Buffer object + ** + ** @return reference to this Commun object + ** + ** @see write() */ + public Commun read( Buffer b) { *************** *** 125,128 **** --- 172,184 ---- } + /** Write data. This method is used to write data + ** from buffer to communication channel (socket). + ** + ** @param b reference to Buffer object + ** + ** @return reference to this Commun object + ** + ** @see read() */ + public Commun write( Buffer b) { *************** *** 144,148 **** --- 200,213 ---- } + /** Failure indication. Use this method if you want to know + ** the last operation was successful or not. + ** + ** @return false (last operation was successful); + ** true (last operation failed) */ + public boolean hasFailed() { return _failed;} + + /** Stop socket communication. It stops socket communication - + ** closes input/output streams and socket. */ public void stopCommun() { Index: IProf.java =================================================================== RCS file: /cvsroot/javaprofiler/library/src2/IProf.java,v retrieving revision 1.8 retrieving revision 1.9 diff -C2 -r1.8 -r1.9 *** IProf.java 2001/09/19 18:57:27 1.8 --- IProf.java 2001/09/23 16:50:15 1.9 *************** *** 48,52 **** public class IProf { ! /** Default constructor. Shared memory is used ** for communication between his Java client and ** profiler dynamic library. */ --- 48,52 ---- public class IProf { ! /** Default constructor. Sockets are used ** for communication between his Java client and [...1208 lines suppressed...] *************** *** 1074,1083 **** ** @return linked list of sID objects ** ! ** @see #getInfo( int, int) ! ** @see #getData( int, int) ! ** @see #getAll( int, int) */ ! public synchronized LinkedList getChanged( int objId, ! int seqType) throws COMMUN_Exception, --- 1226,1232 ---- ** @return linked list of sID objects ** ! ** @see getInfo(), getData(), getAll() */ ! public synchronized LinkedList getChanged( int objId, int seqType) throws COMMUN_Exception, Index: IProfException.java =================================================================== RCS file: /cvsroot/javaprofiler/library/src2/IProfException.java,v retrieving revision 1.2 retrieving revision 1.3 diff -C2 -r1.2 -r1.3 *** IProfException.java 2001/09/02 20:14:22 1.2 --- IProfException.java 2001/09/23 16:50:15 1.3 *************** *** 33,35 **** --- 33,45 ---- */ + /** Exception. All custom exceptions raised by IProf class should be + ** inherited from this class, so it should be very easy to catch + ** exceptions belonging to IProf class. + ** + ** @see BAD_COMMAND_Exception, BAD_DATA_TYPE_Exception, + ** BAD_INFO_ID_Exception, BAD_INFO_TYPE_Exception, + ** BAD_OBJ_ID_Exception, COMMUN_Exception, UNKNOWN_Exception + ** + ** @author Marek Przeczek */ + public class IProfException extends Exception {}; Index: UNKNOWN_Exception.java =================================================================== RCS file: /cvsroot/javaprofiler/library/src2/UNKNOWN_Exception.java,v retrieving revision 1.2 retrieving revision 1.3 diff -C2 -r1.2 -r1.3 *** UNKNOWN_Exception.java 2001/09/02 20:14:22 1.2 --- UNKNOWN_Exception.java 2001/09/23 16:50:15 1.3 *************** *** 33,35 **** --- 33,41 ---- */ + /** Unknown exception. This exception is raised when a failure cannot + ** be recognised, the only thing we know is that it happened in IProf + ** class. + ** + ** @author Marek Przeczek */ + public class UNKNOWN_Exception extends IProfException {}; |