Skip to content

Commit ec4b067

Browse files
trnltrnl
committed
JAVA-839: update ObjectId api
Deprecated: - ObjectId(java.util.Date, int, int) - ObjectId(String,boolean) - ObjectId(int,int,int) - toStringMongod() - toStringBabble() - babbleToMongod() - getTimeSecond() - getMachine() - getInc() - getGenMachineId() - getCurrentInc() - getTime() - isNew() - notNew() - massageToObjectId(Object) - _flip(int) - _inc() - _machine() - _time() Added: - toHexString() - getTimestamp() - getDate() - getCurrentCounter()
1 parent dc2ec29 commit ec4b067

File tree

1 file changed

+170
-8
lines changed

1 file changed

+170
-8
lines changed

‎src/main/org/bson/types/ObjectId.java‎

Lines changed: 170 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,10 @@ public static boolean isValid( String s ){
8282
* be cast and returned. Passing in <code>null</code> returns <code>null</code>.
8383
* @param o the object to convert
8484
* @return an <code>ObjectId</code> if it can be massaged, null otherwise
85+
*
86+
* @deprecated This method is NOT a part of public API and will be dropped in 3.x versions.
8587
*/
88+
@Deprecated
8689
public static ObjectId massageToObjectId( Object o ){
8790
if ( o == null )
8891
return null;
@@ -107,6 +110,12 @@ public ObjectId( Date time , int inc ){
107110
this( time , _genmachine , inc );
108111
}
109112

113+
/**
114+
* @deprecated {@code ObjectId}'s constructed this way do not conform to
115+
* the <a href="http://docs.mongodb.org/manual/reference/object-id/">spec</a>.
116+
* Please use {@link org.bson.types.ObjectId#ObjectId(byte[])} instead.
117+
*/
118+
@Deprecated
110119
public ObjectId( Date time , int machine , int inc ){
111120
_time = (int)(time.getTime() / 1000);
112121
_machine = machine;
@@ -122,6 +131,14 @@ public ObjectId( String s ){
122131
this( s , false );
123132
}
124133

134+
/**
135+
* Constructs a new instance of {@code ObjectId} from a string.
136+
* @param s the string representation of ObjectId. Can contains only [0-9]|[a-f]|[A-F] characters.
137+
* @param babble if {@code true} - convert to 'babble' objectId format
138+
*
139+
* @deprecated 'babble' format is deprecated. Please use {@link #ObjectId(String)} instead.
140+
*/
141+
@Deprecated
125142
public ObjectId( String s , boolean babble ){
126143

127144
if ( ! isValid( s ) )
@@ -156,8 +173,12 @@ public ObjectId( byte[] b ){
156173
* @param time time in seconds
157174
* @param machine machine ID
158175
* @param inc incremental value
176+
* @deprecated {@code ObjectId}'s constructed this way are not conform
177+
* the <a href="http://docs.mongodb.org/manual/reference/object-id/">spec</a>.
178+
* Please use {@link org.bson.types.ObjectId#ObjectId(byte[])} instead.
159179
*/
160-
public ObjectId( int time , int machine , int inc ){
180+
@Deprecated
181+
public ObjectId(int time, int machine, int inc) {
161182
_time = time;
162183
_machine = machine;
163184
_inc = inc;
@@ -195,10 +216,35 @@ public boolean equals( Object o ){
195216
_inc == other._inc;
196217
}
197218

219+
/**
220+
* @deprecated 'babble' format is deprecated. Please use {@link #toHexString()} instead.
221+
*/
222+
@Deprecated
198223
public String toStringBabble(){
199224
return babbleToMongod( toStringMongod() );
200225
}
201226

227+
/**
228+
* Converts this instance into a 24-byte hexadecimal string representation.
229+
*
230+
* @return a string representation of the ObjectId in hexadecimal format
231+
*/
232+
public String toHexString() {
233+
final StringBuilder buf = new StringBuilder(24);
234+
235+
for (final byte b : toByteArray()) {
236+
buf.append(String.format("%02x", b & 0xff));
237+
}
238+
239+
return buf.toString();
240+
}
241+
242+
/**
243+
* @return a string representation of the ObjectId in hexadecimal format
244+
*
245+
* @deprecated Please use {@link #toHexString()} instead.
246+
*/
247+
@Deprecated
202248
public String toStringMongod(){
203249
byte b[] = toByteArray();
204250

@@ -229,6 +275,10 @@ static String _pos( String s , int p ){
229275
return s.substring( p * 2 , ( p * 2 ) + 2 );
230276
}
231277

278+
/**
279+
* @deprecated This method is NOT a part of public API and will be dropped in 3.x versions.
280+
*/
281+
@Deprecated
232282
public static String babbleToMongod( String b ){
233283
if ( ! isValid( b ) )
234284
throw new IllegalArgumentException( "invalid object id: " + b );
@@ -274,56 +324,164 @@ public int compareTo( ObjectId id ){
274324
return _compareUnsigned( _inc , id._inc );
275325
}
276326

277-
public int getMachine(){
327+
/**
328+
* Gets the machine identifier.
329+
*
330+
* @return the machine identifier
331+
*/
332+
public int getMachineIdentifier() {
278333
return _machine;
279334
}
280335

336+
/**
337+
* Gets the machine identifier.
338+
*
339+
* @return the machine identifier
340+
* @deprecated Please use {@code #getMachineIdentifier()} instead.
341+
*/
342+
@Deprecated
343+
public int getMachine() {
344+
return _machine;
345+
}
346+
347+
/**
348+
* Gets the timestamp as a {@code Date} instance.
349+
*
350+
* @return the Date
351+
*/
352+
public Date getDate() {
353+
return new Date(_time * 1000L);
354+
}
355+
281356
/**
282357
* Gets the time of this ID, in milliseconds
358+
*
359+
* @deprecated Please use {@link #getDate()} instead.
283360
*/
361+
@Deprecated
284362
public long getTime(){
285363
return _time * 1000L;
286364
}
287365

288366
/**
289-
* Gets the time of this ID, in seconds
367+
* Gets the timestamp (number of seconds since the Unix epoch).
368+
*
369+
* @return the timestamp
290370
*/
291-
public int getTimeSecond(){
371+
public int getTimestamp() {
292372
return _time;
293373
}
294374

295-
public int getInc(){
375+
/**
376+
* Gets the time of this ID, in seconds.
377+
* @deprecated Please use {@link #getTimestamp()} instead.
378+
*/
379+
@Deprecated
380+
public int getTimeSecond() {
381+
return _time;
382+
}
383+
384+
/**
385+
* Gets the counter.
386+
*
387+
* @return the counter
388+
*/
389+
public int getCounter() {
296390
return _inc;
297391
}
298392

393+
394+
/**
395+
* Gets the counter.
396+
*
397+
* @return the counter
398+
* @see org.bson.types.ObjectId#getCounter()
399+
* @deprecated Please use the {@link #getCounter()} instead.
400+
*/
401+
@Deprecated
402+
public int getInc() {
403+
return _inc;
404+
}
405+
406+
/**
407+
* Gets the timestamp.
408+
*
409+
* @return the timestamp
410+
* @see org.bson.types.ObjectId#getTimestamp()
411+
* @deprecated Please use {@link #getTimestamp()} instead.
412+
*/
413+
@Deprecated
299414
public int _time(){
300415
return _time;
301416
}
417+
418+
/**
419+
* Gets the machine identifier.
420+
*
421+
* @return the machine identifier
422+
* @see org.bson.types.ObjectId#getMachineIdentifier()
423+
* @deprecated Please use {@link #getMachineIdentifier()} instead.
424+
*/
425+
@Deprecated
302426
public int _machine(){
303427
return _machine;
304428
}
429+
430+
/**
431+
* Gets the counter.
432+
*
433+
* @return the counter
434+
* @see org.bson.types.ObjectId#getCounter()
435+
* @deprecated Please use {@link #getCounter()} instead.
436+
*/
437+
@Deprecated
305438
public int _inc(){
306439
return _inc;
307440
}
308441

309-
public boolean isNew(){
442+
/**
443+
* @deprecated 'new' flag breaks the immutability of the {@code ObjectId} class
444+
* and will be dropped in 3.x versions of the driver
445+
*/
446+
@Deprecated
447+
public boolean isNew() {
310448
return _new;
311449
}
312450

451+
/**
452+
* @deprecated 'new' flag breaks the immutability of the {@code ObjectId} class
453+
* and will be dropped in 3.x versions of the driver
454+
*/
455+
@Deprecated
313456
public void notNew(){
314457
_new = false;
315458
}
316459

317460
/**
318-
* Gets the generated machine ID, identifying the machine / process / class loader
461+
* Gets the machine identifier.
462+
*
463+
* @return the machine identifier
464+
* @see org.bson.types.ObjectId#getMachineIdentifier()
465+
* @deprecated Please use {@link #getMachineIdentifier()} instead.
319466
*/
467+
@Deprecated
320468
public static int getGenMachineId() {
321469
return _genmachine;
322470
}
323471

324472
/**
325-
* Gets the current value of the auto increment
473+
* Gets the current value of the auto-incrementing counter.
326474
*/
475+
public static int getCurrentCounter() {
476+
return _nextInc.get();
477+
}
478+
479+
/**
480+
* Gets the current value of the auto-incrementing counter.
481+
*
482+
* @deprecated Please use {@link #getCurrentCounter()} instead.
483+
*/
484+
@Deprecated
327485
public static int getCurrentInc() {
328486
return _nextInc.get();
329487
}
@@ -334,6 +492,10 @@ public static int getCurrentInc() {
334492

335493
boolean _new;
336494

495+
/**
496+
* @deprecated This method is NOT a part of public API and will be dropped in 3.x versions.
497+
*/
498+
@Deprecated
337499
public static int _flip( int x ){
338500
int z = 0;
339501
z |= ( ( x << 24 ) & 0xFF000000 );

0 commit comments

Comments
 (0)