[Jmeter Wiki] Update of "UserManual/Reference/TcpSampler" by JerryAndrews

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Jmeter Wiki" for change notification.

The "UserManual/Reference/TcpSampler" page has been changed by JerryAndrews:
https://wiki.apache.org/jmeter/UserManual/Reference/TcpSampler?action=diff&rev1=2&rev2=3

Comment:
slight additions and updates from the main jmeter web site documentation

- = TCP Sampler (ALPHA Code) =
+ = TCP Sampler =
+ 
+ The TCP Sampler opens a TCP/IP connection to the specified server. It then sends the text, and waits for a response. The actual send/receive behavior is managed by the selected TCPClient.  Three clients are provided (see below).
+ 
+ If "Re-use connection" is selected, connections are shared between Samplers in the same thread, provided that the exact same host name string and port are used. Different hosts/port combinations will use different connections, as will different threads. If both of "Re-use connection" and "Close connection" are selected, the socket will be closed after running the sampler. On the next sampler, another socket will be created. You may want to close a socket at the end of each thread loop. 
+ If an error is detected - or "Re-use connection" is not selected - the socket is closed. Another socket will be reopened on the next sample. 
+ 
+ The following properties can be used to control its operation:
+ 
+ tcp.status.prefix - text that precedes a status number (see"Response Handling", below)
+ <<BR>>tcp.status.suffix - text that follows a status number
+ <<BR>>tcp.status.properties - name of property file to convert status codes to messages (TODO: describe how this works)
+ <<BR>>tcp.handler - Name of TCP Handler class (default TCPClientImpl) - only used if not specified on the GUI
+ 
+ The class that handles the connection is defined by the GUI, failing that the property tcp.handler. If not found, the class is then searched for in the package org.apache.jmeter.protocol.tcp.sampler, e.g. "LengthPrefixedBinaryTCPClientImpl" will be found, as the full classname is org.apache.jmeter.protocol.tcp.sampler.LengthPrefixedBinaryTCPClientImpl.
+ 
+ Users may provide their own TCP client implementation. User classes must extend org.apache.jmeter.protocol.tcp.sampler.TCPClient. The TCPClient writes the supplied message to the socket and receives any response traffic from the socket (subject to the configured timeouts and end-of-line characters).  Place your custom class in a .jar file in [JMeterHome]/lib/ext.
+ 
+ The following implementations are currently provided.
+ 
+  * TCPClientImpl
+  * BinaryTCPClientImpl
+  * LengthPrefixedBinaryTCPClientImpl
+ 
+ The implementations behave as follows:
+ 
+ '''TCPClientImpl'''
+ 
+ This implementation is fairly basic. When reading the response, it reads until the end of line byte, if this is defined by setting the property tcp.eolByte , otherwise until the end of the input stream. You can control charset encoding by setting tcp.charset , which will default to Platform default encoding.
+ 
+ '''BinaryTCPClientImpl'''
+ 
+ This implementation converts the GUI input, which must be a hex-encoded string, into binary, and performs the reverse when reading the response. When reading the response, it reads until the end of message byte, if this is defined by setting the property tcp.BinaryTCPClient.eomByte, otherwise until the end of the input stream. The input text must consist entirely of hex digits without separators.  An even number of digits must be present; the client expects 2 digits per byte to be sent to the socket.  BinayrTCPClientImpl converts server responses back to a hex string for consumption by downstream test elements.
+ 
+ '''LengthPrefixedBinaryTCPClientImpl'''
+ 
+ This implementation extends BinaryTCPClientImpl by prefixing the binary message data with a binary length byte. The length prefix defaults to 2 bytes. This can be changed by setting the property tcp.binarylength.prefix.length .
+ 
+ '''Timeout handling'''
+ 
+ If the timeout is set, the read will be terminated when this expires. If you are using an eolByte/eomByte, make sure the timeout is sufficiently long, otherwise the read will be terminated early.
+ 
+ '''Response handling'''
+ 
+ If tcp.status.prefix is defined, the response message is searched for the text following that up to the suffix. If any such text is found, it is used to set the response code. The response message is then fetched from the properties file (if provided). For example, if the prefix = "[" and the suffix = "]", then the following response: 
+ 
+ {{{[J28] XI123,23,GBP,CR}}}
+ 
+ would have the response code J28. 
+ 
+ Response codes in the range "400"-"499" and "500"-"599" are currently regarded as failures; all others are successful. [This needs to be made configurable!]
+ 
+ The login name/password are not used by the supplied TCP implementations.
+ 
+ Sockets are disconnected at the end of a test run.
+ 
+ If you choose to supply your own TCPClient, you will be reading the response from the server and may generate your own response codes as described above ("400"-"499" & "500"-"599" indicate failure; anything else is success).
  
  '''Parameters'''
  || '''Attribute''' || '''Description''' || '''Required''' ||
  || '''Name''' || Descriptive name for this element that is shown in the tree. || No ||
+ || '''Comments''' || text for the test user's use. || No ||
+ || '''TCPClient classname''' || Name of the TCPClient class. Defaults to the property tcp.handler, failing that TCPClientImpl. || No ||
+ || '''Server Name or IP''' || Name or IP of TCP server || Yes ||
+ || '''Port Number''' || Port to be used. || Yes ||
+ || '''Timeouts: Connect''' || Connect Timeout (milliseconds, 0 disables). || No ||
+ || '''Timeouts: Response''' || Response Timeout (milliseconds, 0 disables). || No ||
+ || '''Re-use connection''' || If selected, the connection is kept open. Otherwise it is closed when the data has been read. || Yes ||
+ || '''Close connection''' || If selected, the connection will be closed after running the sampler. || Yes ||
+ || '''Set NoDelay''' || See java.net.Socket.setTcpNoDelay(). If selected, this will disable Nagle's algorithm, otherwise Nagle's algorithm will be used. || No ||
+ || '''SO_LINGER''' || Enable/disable SO_LINGER with the specified linger time in seconds when a socket is created. If you set "SO_LINGER" value as 0, you may prevent large numbers of sockets sitting around with a TIME_WAIT status. || No ||
+ || '''End of line(EOL) byte value''' || Byte value for end of line, set this to a value outside the range -128 to +127 to skip eol checking. You may set this in jmeter.properties file as well with eolByte property. If you set this in TCP Sampler Config and in jmeter.properties file at the same time, the setting value in the TCP Sampler Config will be used. || No ||
+ || '''Text to send''' || Text to be sent (see TCPClient descriptions above). || No ||
+ || '''Username''' || User Name - not used by default implementation. || No ||
+ || '''Password''' || Password - not used by default implementation (N.B. this is stored unencrypted in the test plan). || No ||