org.bson.types

Class ObjectId

java.lang.Object

org.bson.types.ObjectId

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<ObjectId>

public final class ObjectId
extends java.lang.Object
implements java.lang.Comparable<ObjectId>, java.io.Serializable

A globally unique identifier for objects.

Consists of 12 bytes, divided as follows:

ObjectID layout

0	1	2	3	4	5	6	7	8	9	10	11
time				random value					inc

Instances of this class are immutable.

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
ObjectId() Create a new object id.
ObjectId(byte[] bytes) Constructs a new instance from the given byte array
ObjectId(java.nio.ByteBuffer buffer) Constructs a new instance from the given ByteBuffer
ObjectId(java.util.Date date) Constructs a new instance using the given date.
ObjectId(java.util.Date date, int counter) Constructs a new instances using the given date and counter.
ObjectId(java.util.Date date, int machineIdentifier, short processIdentifier, int counter) Deprecated. Use ObjectId(Date, int) instead
ObjectId(int timestamp, int counter) Creates an ObjectId using the given time, machine identifier, process identifier, and counter.
ObjectId(int timestamp, int machineIdentifier, short processIdentifier, int counter) Deprecated. Use ObjectId(int, int) instead
ObjectId(java.lang.String hexString) Constructs a new instance from a 24-byte hexadecimal string representation.

Method Summary

Modifier and Type	Method and Description
int	compareTo(ObjectId other)
static ObjectId	createFromLegacyFormat(int time, int machine, int inc) Deprecated. Use ObjectId(int, int) instead
boolean	equals(java.lang.Object o)
static ObjectId	get() Gets a new object id.
int	getCounter() Deprecated.
static int	getCurrentCounter() Deprecated.
java.util.Date	getDate() Gets the timestamp as a Date instance.
static int	getGeneratedMachineIdentifier() Deprecated.
static int	getGeneratedProcessIdentifier() Deprecated.
int	getMachineIdentifier() Deprecated.
short	getProcessIdentifier() Deprecated.
long	getTime() Deprecated. Use #getDate instead
int	getTimeSecond() Deprecated. Use #getTimestamp instead
int	getTimestamp() Gets the timestamp (number of seconds since the Unix epoch).
int	hashCode()
static boolean	isValid(java.lang.String hexString) Checks if a string could be an ObjectId.
void	putToByteBuffer(java.nio.ByteBuffer buffer) Convert to bytes and put those bytes to the provided ByteBuffer.
byte[]	toByteArray() Convert to a byte array.
java.lang.String	toHexString() Converts this instance into a 24-byte hexadecimal string representation.
java.lang.String	toString()
java.lang.String	toStringMongod() Deprecated. use toHexString()

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ObjectId

public ObjectId()

Create a new object id.

ObjectId

public ObjectId(java.util.Date date)

Constructs a new instance using the given date.

Parameters:

date - the date

ObjectId

public ObjectId(java.util.Date date,
                int counter)

Constructs a new instances using the given date and counter.

Parameters:

date - the date

counter - the counter

Throws:

java.lang.IllegalArgumentException - if the high order byte of counter is not zero

ObjectId

@Deprecated
public ObjectId(java.util.Date date,
                            int machineIdentifier,
                            short processIdentifier,
                            int counter)

Deprecated. Use ObjectId(Date, int) instead

Constructs a new instances using the given date, machine identifier, process identifier, and counter.

Parameters:

date - the date

machineIdentifier - the machine identifier

processIdentifier - the process identifier

counter - the counter

Throws:

java.lang.IllegalArgumentException - if the high order byte of machineIdentifier or counter is not zero

ObjectId

@Deprecated
public ObjectId(int timestamp,
                            int machineIdentifier,
                            short processIdentifier,
                            int counter)

Deprecated. Use ObjectId(int, int) instead

Creates an ObjectId using the given time, machine identifier, process identifier, and counter.

Parameters:

timestamp - the time in seconds

machineIdentifier - the machine identifier

processIdentifier - the process identifier

counter - the counter

Throws:

java.lang.IllegalArgumentException - if the high order byte of machineIdentifier or counter is not zero

ObjectId

public ObjectId(int timestamp,
                int counter)

Creates an ObjectId using the given time, machine identifier, process identifier, and counter.

Parameters:

timestamp - the time in seconds

counter - the counter

Throws:

java.lang.IllegalArgumentException - if the high order byte of counter is not zero

ObjectId

public ObjectId(java.lang.String hexString)

Constructs a new instance from a 24-byte hexadecimal string representation.

Parameters:

hexString - the string to convert

Throws:

java.lang.IllegalArgumentException - if the string is not a valid hex string representation of an ObjectId

ObjectId

public ObjectId(byte[] bytes)

Constructs a new instance from the given byte array

Parameters:

bytes - the byte array

Throws:

java.lang.IllegalArgumentException - if array is null or not of length 12

ObjectId

public ObjectId(java.nio.ByteBuffer buffer)

Constructs a new instance from the given ByteBuffer

Parameters:

buffer - the ByteBuffer

Throws:

java.lang.IllegalArgumentException - if the buffer is null or does not have at least 12 bytes remaining

Since:

3.4

Method Detail

get

public static ObjectId get()

Gets a new object id.

Returns:

the new id

isValid

public static boolean isValid(java.lang.String hexString)

Checks if a string could be an ObjectId.

Parameters:

hexString - a potential ObjectId as a String.

Returns:

whether the string could be an object id

Throws:

java.lang.IllegalArgumentException - if hexString is null

toByteArray

public byte[] toByteArray()

Convert to a byte array. Note that the numbers are stored in big-endian order.

Returns:

the byte array

putToByteBuffer

public void putToByteBuffer(java.nio.ByteBuffer buffer)

Convert to bytes and put those bytes to the provided ByteBuffer. Note that the numbers are stored in big-endian order.

Parameters:

buffer - the ByteBuffer

Throws:

java.lang.IllegalArgumentException - if the buffer is null or does not have at least 12 bytes remaining

Since:

3.4

getTimestamp

public int getTimestamp()

Gets the timestamp (number of seconds since the Unix epoch).

Returns:

the timestamp

getDate

public java.util.Date getDate()

Gets the timestamp as a Date instance.

Returns:

the Date

toHexString

public java.lang.String toHexString()

Converts this instance into a 24-byte hexadecimal string representation.

Returns:

a string representation of the ObjectId in hexadecimal format

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

compareTo

public int compareTo(ObjectId other)

Specified by:

compareTo in interface java.lang.Comparable<ObjectId>

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

createFromLegacyFormat

@Deprecated
public static ObjectId createFromLegacyFormat(int time,
                                                          int machine,
                                                          int inc)

Deprecated. Use ObjectId(int, int) instead

Creates an ObjectId using time, machine and inc values. The Java driver used to create all ObjectIds this way, but it does not match the ObjectId specification, which requires four values, not three. This major release of the Java driver conforms to the specification, but still supports clients that are relying on the behavior of the previous major release by providing this explicit factory method that takes three parameters instead of four.

Ordinary users of the driver will not need this method. It's only for those that have written there own BSON decoders.

NOTE: This will not break any application that use ObjectIds. The 12-byte representation will be round-trippable from old to new driver releases.

Parameters:

time - time in seconds

machine - machine ID

inc - incremental value

Returns:

a new ObjectId created from the given values

Since:

2.12.0

getCurrentCounter

@Deprecated
public static int getCurrentCounter()

Deprecated.

Gets the current value of the auto-incrementing counter.

Returns:

the current counter value.

getGeneratedMachineIdentifier

@Deprecated
public static int getGeneratedMachineIdentifier()

Deprecated.

Gets the generated machine identifier.

Returns:

an int representing the machine identifier

getGeneratedProcessIdentifier

@Deprecated
public static int getGeneratedProcessIdentifier()

Deprecated.

Gets the generated process identifier.

Returns:

the process id

getMachineIdentifier

@Deprecated
public int getMachineIdentifier()

Deprecated.

Gets the machine identifier.

Returns:

the machine identifier

getProcessIdentifier

@Deprecated
public short getProcessIdentifier()

Deprecated.

Gets the process identifier.

Returns:

the process identifier

getCounter

@Deprecated
public int getCounter()

Deprecated.

Gets the counter.

Returns:

the counter

getTimeSecond

@Deprecated
public int getTimeSecond()

Deprecated. Use #getTimestamp instead

Gets the time of this ID, in seconds.

Returns:

the time component of this ID in seconds

getTime

@Deprecated
public long getTime()

Deprecated. Use #getDate instead

Gets the time of this instance, in milliseconds.

Returns:

the time component of this ID in milliseconds

toStringMongod

@Deprecated
public java.lang.String toStringMongod()

Deprecated. use toHexString()

Returns:

a string representation of the ObjectId in hexadecimal format

See Also:

toHexString()