AbstractIpp (J4Cups 0.6.1 API)

java.lang.Object
- j4cups.protocol.AbstractIpp

All Implemented Interfaces:: java.io.Externalizable, java.io.Serializable

Direct Known Subclasses:: IppRequest, IppResponse

public abstract class AbstractIpp
extends java.lang.Object
implements java.io.Externalizable

The class AbstractIpp is the common super class of IppRequest and IppResponse which encapsulates the common code of both classes. An operation request or response is defined in RFC-2910:

  -----------------------------------------------
  |                  version-number             |   2 bytes  - required
  -----------------------------------------------
  |               operation-id (request)        |
  |                      or                     |   2 bytes  - required
  |               status-code (response)        |
  -----------------------------------------------
  |                   request-id                |   4 bytes  - required
  -----------------------------------------------
  |                 attribute-group             |   n bytes - 0 or more
  -----------------------------------------------
  |              end-of-attributes-tag          |   1 byte   - required
  -----------------------------------------------
  |                     data                    |   q bytes  - optional
  -----------------------------------------------

Since:: 0.2 (16.02.2018)
Author:: oboehm
See Also:: Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class AbstractIpp.Version
Container for the version information.

Nested Classes
Modifier and Type	Class and Description
`static class`	`AbstractIpp.Version` Container for the version information.

Field Summary

Fields
Modifier and Type Field and Description

protected static AbstractIpp.Version DEFAULT_VERSION
The actual supported version is 2.

Fields
Modifier and Type	Field and Description
`protected static AbstractIpp.Version`	`DEFAULT_VERSION` The actual supported version is 2.

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`AbstractIpp()` This constructor is needed for the `Externalizable` interface.
	`AbstractIpp(AbstractIpp.Version version, short opCode, int requestId, java.util.List<AttributeGroup> groups)` Instantiates a new IPP request or response with no data.
	`AbstractIpp(AbstractIpp.Version version, short opCode, int requestId, java.util.List<AttributeGroup> groups, byte[] data)` Instantiates a new IPP request or response.
`protected`	`AbstractIpp(byte[] bytes)` Instantiates a new IPP request or responsel from the given bytes.
	`AbstractIpp(java.nio.ByteBuffer bytes)` Instantiates a new IPP request or response from the given bytes.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addAttributeGroup(AttributeGroup group)` Adds the given group.
`boolean`	`equals(java.lang.Object obj)` The binary representation of this class is used to compare to request or respone objects.
`Attribute`	`getAttribute(java.lang.String name)` Gets the attribute with the given name.
`AttributeGroup`	`getAttributeGroup(DelimiterTags tag)` Returns all attributes of the given delimiter-tag.
`java.util.List<AttributeGroup>`	`getAttributeGroups()` The fourth field is the "attribute-group" field, and it occurs 0 or more times.
`java.util.List<Attribute>`	`getAttributes()` Gets a collected list of all attributes of the attribute-groups.
`byte[]`	`getData()` Returns the data part of the request.
`int`	`getJobId()` Returns the job-id of the request or response.
`JobState`	`getJobState()` Returns the job-state of the request or response.
`java.lang.String`	`getJobStateMessage()` Returns the job-state-message of the request or response.
`JobStateReasons`	`getJobStateReasons()` Returns the job-state-reason of the request or response.
`java.net.URI`	`getJobURI()` Returns the job-uri of the request or response.
`long`	`getLength()` Calculates the size of the request or response.
`short`	`getOpCode()` Returns the 2nd part (byte 2-3) with the operation-id or status-code.
`protected abstract java.lang.String`	`getOpCodeAsString()` Returns the 2nd part (byte 2-3) with the operation-id or status-code as string.
`java.util.List<Attribute>`	`getOperationAttributes()` Gets a collected list of all operation attributes.
`java.net.URI`	`getPrinterURI()` Gets the URI of the printer from the attributes.
`int`	`getRequestId()` Returns the 3rd part (byte 4-7) of the request which contains the request-id.
`AbstractIpp.Version`	`getVersion()` Gets the first part (byte 0-1) with the supported IPP version.
`boolean`	`hasAttribute(java.lang.String name)` Checks the attribute with the given name.
`boolean`	`hasData()` The data part of the request can be empty.
`int`	`hashCode()`
`void`	`readExternal(java.io.ObjectInput in)` The object implements the readExternal method to restore its contents by reading the byte array and use this array to build up an IPP request or response.
`void`	`recordTo(java.nio.file.Path logDir)` This method allows you to record a IPP package into a file.
`static void`	`recordTo(java.nio.file.Path logDir, byte[] bytes, java.lang.String name)` This method is public because it is used also by other methods.
`void`	`setAttribute(Attribute attr, DelimiterTags groupTag)` Sets the attribute into the group defined by the groupTag.
`void`	`setAttribute(java.lang.String name, byte[] value)` Sets the attribute with the given name.
`void`	`setAttributesCharset(java.nio.charset.Charset charset)` Sets the attributes-charset attribute.
`void`	`setAttributesNaturalLanguage(java.util.Locale locale)` Sets the attributes-natural-language attribute.
`void`	`setData(byte[] data)` Sets the data part of the request or response.
`void`	`setJobAttribute(Attribute attr)` Sets the job attribute.
`void`	`setJobId(int id)` Sets the job-id.
`void`	`setJobState(JobState state)` Sets the job-state.
`void`	`setJobStateMessage(java.lang.String msg)` Sets the job-state-message.
`void`	`setJobStateReasons(JobStateReasons reason)` Sets the job-state-rease.
`void`	`setJobURI(java.net.URI uri)` Sets the job-uri.
`void`	`setOpCode(short opCode)` Sets the 2nd part (byte 2-3) with the new operation-id or status-code.
`void`	`setOperationAttribute(Attribute attr)` Sets the operation attribute.
`void`	`setPrinterURI(java.net.URI printerURI)` Sets the printer-uri attribute.
`void`	`setRequestId(int id)` Sets the request-id.
`void`	`setRequestingUserName(java.lang.String username)` Sets the requesting-user-name attribute.
`byte[]`	`toByteArray()` Converts the IppResponse to a byte array as described in RFC-2910.
`java.lang.String`	`toLongString()` Puts all attribute information into the resulting string.
`java.lang.String`	`toShortString()` Provides a shorter version with only the main elements and attributes.
`java.lang.String`	`toString()` With this toString() implementation we want to provide the most important values which are useful for logging and debugging.
`void`	`validate()` Validates an request.
`void`	`writeExternal(java.io.ObjectOutput out)` The object implements the writeExternal method to save its contents by storing it as byte array.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - DEFAULT_VERSION
```
protected static final AbstractIpp.Version DEFAULT_VERSION
```
    The actual supported version is 2.
- Constructor Detail
  - AbstractIpp
```
protected AbstractIpp()
```
    This constructor is needed for the Externalizable interface.
  - AbstractIpp
```
protected AbstractIpp(byte[] bytes)
```
    Instantiates a new IPP request or responsel from the given bytes.
    
    Parameters:
    
    bytes - the bytes of the IPP request
  - AbstractIpp
```
public AbstractIpp(java.nio.ByteBuffer bytes)
```
    Instantiates a new IPP request or response from the given bytes.
    
    Parameters:
    
    bytes - the bytes of the IPP request
  - AbstractIpp
```
public AbstractIpp(AbstractIpp.Version version,
                   short opCode,
                   int requestId,
                   java.util.List<AttributeGroup> groups)
```
    Instantiates a new IPP request or response with no data.
    
    Parameters:
    
    version - the version
    
    opCode - the code for operation-id or status-code
    
    requestId - the request id
    
    groups - the attribute groups
  - AbstractIpp
```
public AbstractIpp(AbstractIpp.Version version,
                   short opCode,
                   int requestId,
                   java.util.List<AttributeGroup> groups,
                   byte[] data)
```
    Instantiates a new IPP request or response.
    
    Parameters:
    
    version - the version
    
    opCode - the code for operation-id or status-code
    
    requestId - the request id
    
    groups - the attribute groups
    
    data - the data
- Method Detail
  - recordTo
```
public void recordTo(java.nio.file.Path logDir)
```
    This method allows you to record a IPP package into a file. Watcht the log to see where the file is stored.
    
    Parameters:
    
    logDir - the directory where the file is stored
    
    Since:
    
    0.5
  - recordTo
```
public static void recordTo(java.nio.file.Path logDir,
                            byte[] bytes,
                            java.lang.String name)
```
    This method is public because it is used also by other methods.
    
    Parameters:
    
    logDir - logging directory
    
    bytes - data to be recorded
    
    name - suffix, which is used as filename
  - getVersion
```
public AbstractIpp.Version getVersion()
```
    Gets the first part (byte 0-1) with the supported IPP version. This is a number from 1.0 till 1.4 for version 1 or 2.0 for version 2.
    
    Returns:
    
    e.g. "2.0"
  - setOpCode
```
public void setOpCode(short opCode)
```
    Sets the 2nd part (byte 2-3) with the new operation-id or status-code.
    
    Parameters:
    
    opCode - e.g.0x0000 for status-code 'successful_ok'
  - getOpCode
```
public short getOpCode()
```
    Returns the 2nd part (byte 2-3) with the operation-id or status-code.
    
    Returns:
    
    e.g. 0x0005 for 'Create-Job'
  - getOpCodeAsString
```
protected abstract java.lang.String getOpCodeAsString()
```
    Returns the 2nd part (byte 2-3) with the operation-id or status-code as string.
    
    Returns:
    
    e.g. "Create-Job"
  - getRequestId
```
public int getRequestId()
```
    Returns the 3rd part (byte 4-7) of the request which contains the request-id.
    
    Returns:
    
    the request-id
  - setRequestId
```
public void setRequestId(int id)
```
    Sets the request-id.
    
    Parameters:
    
    id - the new request-id
    
    Since:
    
    0.5
  - getJobId
```
public int getJobId()
```
    Returns the job-id of the request or response.
    
    Returns:
    
    a positiv number
    
    Since:
    
    0.5
  - setJobId
```
public void setJobId(int id)
```
    Sets the job-id.
    
    Parameters:
    
    id - the new job-id
    
    Since:
    
    0.5
  - getJobState
```
public JobState getJobState()
```
    Returns the job-state of the request or response.
    
    Returns:
    
    a job state
    
    Since:
    
    0.5
  - setJobState
```
public void setJobState(JobState state)
```
    Sets the job-state.
    
    Parameters:
    
    state - the new job-state
    
    Since:
    
    0.5
  - getJobStateReasons
```
public JobStateReasons getJobStateReasons()
```
    Returns the job-state-reason of the request or response.
    
    Returns:
    
    the job-state-reason
    
    Since:
    
    0.5
  - setJobStateReasons
```
public void setJobStateReasons(JobStateReasons reason)
```
    Sets the job-state-rease.
    
    Parameters:
    
    reason - the new job-state-reason
    
    Since:
    
    0.5
  - getJobStateMessage
```
public java.lang.String getJobStateMessage()
```
    Returns the job-state-message of the request or response.
    
    Returns:
    
    the job-state-message
    
    Since:
    
    0.5
  - setJobStateMessage
```
public void setJobStateMessage(java.lang.String msg)
```
    Sets the job-state-message.
    
    Parameters:
    
    msg - the new message
    
    Since:
    
    0.5
  - getJobURI
```
public java.net.URI getJobURI()
```
    Returns the job-uri of the request or response.
    
    Returns:
    
    URI, e.g. "ipp://localhost:631/jobs/101"
    
    Since:
    
    0.5
  - setJobURI
```
public void setJobURI(java.net.URI uri)
```
    Sets the job-uri.
    
    Parameters:
    
    uri - the new job-uri
    
    Since:
    
    0.5
  - getAttributeGroups
```
public java.util.List<AttributeGroup> getAttributeGroups()
```
    The fourth field is the "attribute-group" field, and it occurs 0 or more times.
    
    Returns:
    
    a list of attribute-groups
  - addAttributeGroup
```
public void addAttributeGroup(AttributeGroup group)
```
    Adds the given group. I.e. group of 'printer-attributs-tag' can be set several times.
    
    Parameters:
    
    group - the group
    
    Since:
    
    0.5
  - getAttributeGroup
```
public AttributeGroup getAttributeGroup(DelimiterTags tag)
```
    Returns all attributes of the given delimiter-tag.
    
    Parameters:
    
    tag - the delimiter-tag
    
    Returns:
    
    list of attributes
  - getAttributes
```
public java.util.List<Attribute> getAttributes()
```
    Gets a collected list of all attributes of the attribute-groups.
    
    Returns:
    
    list of all attibutes
  - setAttribute
```
public void setAttribute(java.lang.String name,
                         byte[] value)
```
    Sets the attribute with the given name. If it exits the old value will be overridden. If it does not exist it will be inserted in the unsupported attribute-groups section with "unknown" as value tag.
    
    Parameters:
    
    name - name of the attribute
    
    value - byte values of the attribute
    
    See Also:
    
    setAttribute(Attribute, DelimiterTags)
  - setAttribute
```
public void setAttribute(Attribute attr,
                         DelimiterTags groupTag)
```
    Sets the attribute into the group defined by the groupTag.
    
    Parameters:
    
    attr - the attribute
    
    groupTag - defines the attribute-group where the attribute is inserted
  - getAttribute
```
public Attribute getAttribute(java.lang.String name)
```
    Gets the attribute with the given name. If not attribute with the given name is not found an IllegalArgumentException will be thrown.
    
    Parameters:
    
    name - name of the attribute
    
    Returns:
    
    attribute with given name
  - hasAttribute
```
public boolean hasAttribute(java.lang.String name)
```
    Checks the attribute with the given name.
    
    Parameters:
    
    name - name of the attribute
    
    Returns:
    
    true or false
    
    Since:
    
    0.5
  - setOperationAttribute
```
public void setOperationAttribute(Attribute attr)
```
    Sets the operation attribute.
    
    Parameters:
    
    attr - attribute
    
    Since:
    
    0.5
  - setJobAttribute
```
public void setJobAttribute(Attribute attr)
```
    Sets the job attribute.
    
    Parameters:
    
    attr - attribute
    
    Since:
    
    0.5
  - getOperationAttributes
```
public java.util.List<Attribute> getOperationAttributes()
```
    Gets a collected list of all operation attributes.
    
    Returns:
    
    list of operation attibutes
    
    Since:
    
    0.5
  - getPrinterURI
```
public java.net.URI getPrinterURI()
```
    Gets the URI of the printer from the attributes.
    
    Returns:
    
    printer-uri
    
    Since:
    
    0.5
  - setPrinterURI
```
public void setPrinterURI(java.net.URI printerURI)
```
    Sets the printer-uri attribute. If it is already set it will be overwritten.
    
    Parameters:
    
    printerURI - the printer uri
    
    Since:
    
    0.5
  - setAttributesCharset
```
public void setAttributesCharset(java.nio.charset.Charset charset)
```
    Sets the attributes-charset attribute.
    
    Parameters:
    
    charset - e.g. UTF_8
    
    Since:
    
    0.5
  - setAttributesNaturalLanguage
```
public void setAttributesNaturalLanguage(java.util.Locale locale)
```
    Sets the attributes-natural-language attribute.
    
    Parameters:
    
    locale - e.g. GERMANY
    
    Since:
    
    0.5
  - setRequestingUserName
```
public void setRequestingUserName(java.lang.String username)
```
    Sets the requesting-user-name attribute.
    
    Parameters:
    
    username - user name
    
    Since:
    
    0.5
  - setData
```
public void setData(byte[] data)
```
    Sets the data part of the request or response.
    
    Parameters:
    
    data - new data
    
    Since:
    
    0.3
  - getData
```
public byte[] getData()
```
    Returns the data part of the request. If no data part is present a 0-length byte array is returned.
    
    Returns:
    
    data part
  - hasData
```
public boolean hasData()
```
    The data part of the request can be empty.
    
    Returns:
    
    false if data part is empty, true otherwise
  - toString
```
public java.lang.String toString()
```
    With this toString() implementation we want to provide the most important values which are useful for logging and debugging.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    a String with operation, request-id and other stuff
  - toShortString
```
public java.lang.String toShortString()
```
    Provides a shorter version with only the main elements and attributes.
    
    Returns:
    
    a string with operation and main operation attributes
    
    Since:
    
    0.5
  - toLongString
```
public java.lang.String toLongString()
```
    Puts all attribute information into the resulting string. The data value may be abbreviated if it is too long. But you can set the log level to TRACE if you want to record the full request.
    
    Returns:
    
    string with all attribute values
  - toByteArray
```
public byte[] toByteArray()
```
    Converts the IppResponse to a byte array as described in RFC-2910.
```
  -----------------------------------------------
  |                  version-number             |   2 bytes  - required
  -----------------------------------------------
  |          operation-id or status-code        |   2 bytes  - required
  -----------------------------------------------
  |                   request-id                |   4 bytes  - required
  -----------------------------------------------
  |                 attribute-group             |   n bytes - 0 or more
  -----------------------------------------------
  |              end-of-attributes-tag          |   1 byte   - required
  -----------------------------------------------
  |                     data                    |   q bytes  - optional
  -----------------------------------------------
 
```
    Returns:
    
    at least 9 bytes
  - getLength
```
public long getLength()
```
    Calculates the size of the request or response.
    
    Returns:
    
    length in bytes
  - writeExternal
```
public void writeExternal(java.io.ObjectOutput out)
                   throws java.io.IOException
```
    The object implements the writeExternal method to save its contents by storing it as byte array.
    
    Specified by:
    
    writeExternal in interface java.io.Externalizable
    
    Parameters:
    
    out - the stream to write the object to
    
    Throws:
    
    java.io.IOException - Includes any I/O exceptions that may occur
  - readExternal
```
public void readExternal(java.io.ObjectInput in)
                  throws java.io.IOException
```
    The object implements the readExternal method to restore its contents by reading the byte array and use this array to build up an IPP request or response.
    
    Specified by:
    
    readExternal in interface java.io.Externalizable
    
    Parameters:
    
    in - the stream to read data from in order to restore the object
    
    Throws:
    
    java.io.IOException - if I/O errors occur
  - validate
```
public void validate()
```
    Validates an request. If it is not valid (e.g. if it has several attribute-groups of the same type) a ValidationException will be thrown.
    
    Since:
    
    0.5.1
  - equals
```
public boolean equals(java.lang.Object obj)
```
    The binary representation of this class is used to compare to request or respone objects. I.e. for two objects the attributes must be defined not only with same values but also in the same order to be equal.
    
    Overrides:
    
    equals in class java.lang.Object
    
    Parameters:
    
    obj - the other response or request
    
    Returns:
    
    true if they are equals
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class java.lang.Object

Class AbstractIpp

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_VERSION

Constructor Detail

AbstractIpp

AbstractIpp

AbstractIpp

AbstractIpp

AbstractIpp

Method Detail

recordTo

recordTo

getVersion

setOpCode

getOpCode

getOpCodeAsString

getRequestId

setRequestId

getJobId

setJobId

getJobState

setJobState

getJobStateReasons

setJobStateReasons

getJobStateMessage

setJobStateMessage

getJobURI

setJobURI

getAttributeGroups

addAttributeGroup

getAttributeGroup

getAttributes

setAttribute

setAttribute

getAttribute

hasAttribute

setOperationAttribute

setJobAttribute

getOperationAttributes

getPrinterURI

setPrinterURI

setAttributesCharset

setAttributesNaturalLanguage

setRequestingUserName

setData

getData

hasData

toString

toShortString

toLongString

toByteArray

getLength

writeExternal

readExternal

validate

equals

hashCode