Package util.adt deprecated

With the implementation of RFC #0057 (see entry #87) the classes of the util.adt package have been deprecated.

Note: The old classes will remain in the codebase for the moment and can still be used, although they may not be used together with the new classes due name clashes resulting from PHP's lack of namespaces.

Continue reading for migration notes.

The collections framework RFC comes with a migration script that takes care of rewriting your sourcecode to use the new classes from util.collections.

General migration procedure
Use it as follows: $ php rfc57-migration.php [[directory]] (assuming your XP checkout is located in ~/devel/xp/trunk, use $ php rfc57-migration.php ~/devel/xp/trunk). The script will analyze the files below this directory recursively and print a list of matches it has found. By supplying -e (for execute) after the directory's name, the changes will actually be written, too.

Done

The LRUBuffer issue
The LRUBuffer class has changed in a way that is backwards-incompatible. As stated above, you may continue to use the old class but should migrate at the first chance since the util.adt version of the LRUBuffer class is deprecated.

The new classes are designed to work only with Objects (for example, the HashTable class supports objects as keys and values). The LRUBuffer class used to accept primitives as arguments for its add() and update() methods, the new version requires Objects.

The migration script will print the following if it finds the LRUBuffer class was used in your sourcecode:

---> Processing SearchState.class.php with LRUBufferUsageFinder{}
     >> Variable $lru points to an LRUBuffer instance at line 200
     >> Method add invoked on $lru with ($stamp) at line 206
***  1 occurence(s) of LRUBuffer usage found (see above for details)
***  Automatic migration is not possible!

<?php 
  $lru= &$request->session->getValue('lru');
?>

As HttpSession::getValue() returns "mixed" (basically, anything), we cannot derive the lru variable's type (by a grep, that is, in case we'd actually execute the sourcecode, we could, but we don't want that for good reasons).

• add() now takes Objects instead of primitives
  The code at the source position mentioned above is something like:
  

  <?php 
    $lru= &new LRUBuffer(5);
    $stamp= $record['order_id'];
    $lru->add($stamp);
  ?>

  
  and could be rewritten using the wrapper types from lang.types, e.g.:
  

  <?php 
    $lru= &new LRUBuffer(5);
    $stamp= $record['order_id'];
    $lru->add(new Integer($stamp));
  ?>

  
  The problem is we cannot guess the correct wrapper type ($record['order_id'] originates from an SQL query).
  
• The victim object is returned instead of the position
  In case you use the return value, careful steps need to be taken to migrate your sourcecode.
  

  <?php 
    $deleted= $lru->add($stamp);
  
    // util.adt.LRUBuffer::add() returns NULL when nothing has been deleted,
    // an int with the LRUBuffers' internal list offset otherwise
    if (NULL !== $deleted) {
      Console::writeLine('Deleted element #', $deleted);
    }
  ?>

  
  would need to be rewritten to:
  

  <?php 
    $deleted= &$lru->add(new Integer($stamp));
  
    // util.collections.LRUBuffer::add() returns NULL when nothing has been deleted,
    // the victim object otherwise
    if ($deleted) {
      Console::writeLine('Victim was: ', $deleted->toString());
    }
  ?>

  
  

• add() now takes Objects instead of primitives
  Same steps as for add() apply here.
  

Subscribe

You can subscribe to the XP framework's news by using RSS syndication.

Categories

Related

Find related articles by a search for «Package».