Bukkit

PowerNBT API

PowerNBT API v. 0.7.2 and later
Api Javadoc

NBTManager

me.dpohvar.powernbt.api.NBTManager
NBTManager has methods to read and write NBT tags

NBTManager manager = PowerNBT.getApi();

Full documentation available in github
simple useless example:

NBTCompound playerData = manager.read(player);
float health = (Float) playerData.get("HealF");
if (health>15) playerData.put("HealF",(float)5);
manager.write(player, playerData);

NBTManager can read tags of entities, blocks, files, items,
read nbt from inputstream and datainput,
save nbt to outputstream and dataoutput,
compress nbt and save to outputstream or file
read compressed nbt
read forge data of entity and save
read offline player's .dat file and save

NBTCompound

me.dpohvar.powernbt.api.NBTCompound
this class represents net.minecraft.server.NBTTagCompound
You can work with nbt as with lazy java.util.Map<String,Object>
The changes are immediately applied to the original NBTTagCompound
but NBTCompound has extra methods: getByte(), getShort(), getString(), etc..

Difference from java.util.Map

• NBTCompound can contains only values of types:
  Byte, Short, Integer, Long, Float, Double, byte[], String, NBTList, NBTCompound, int[]
  But you can put to compound any value that can be converted to types above
  Boolean will be converted to Byte (0, 1),
  java.util.Collection and Object[] will be converted to NBTList,
  java.util.Map will be converted to NBTCompound

• Methods which add items into compound creates a copy of tag:
  See example:

  NBTCompound cmp = new NBTCompound(); // cmp = {}
  NBTCompound cmp2 = new NBTCompound(); // cmp2 = {}
  cmp.put("cmp2",cmp2);  // put to cmp a copy of cmp2
  cmp2.put("foo","bar"); // cmp2 = {foo:bar}
  cmp,get("cmp2"); // returns empty compound
  

• NBTCompound can not contain cross-references:
  Example:

  NBTCompound cmp = new NBTCompound(); // cmp = {}
  cmp.put("foo","bar"); // cmp = {foo:bar}
  cmp.put("cmp",cmp);  // put to cmp a copy of self
  System.out.println(cmp); // {foo:bar, cmp:{foo:bar}}
  

• NBTCompound can not contain empty keys or values:
  Example:

  NBTCompound cmp = new NBTCompound(); // cmp = {}
  cmp.put("foo","bar"); // add pair foo:bar
  System.out.println(cmp); // {foo:bar}
  cmp.put("foo",null);  // remove foo
  assert !cmp.containsKey("foo"); // now cmp is empty
  

Convert NBTCompound to java.util.Map

TreeMap<String,Object> treeMap = compound.toMap(new TreeMap<>());
HashMap<String,Object> hashMap = compound.toHashMap();

now treeMap and hashMap contains only java Values:
Byte, Short, Integer, Long, Float, Double, byte[], String, List, Map, int[]

Convert java.util.Map to NBTCompound

NBTCompound compound = new NBTCompound(map); // it's easy, right?

But be sure, that map does not contain cross-references!

Full documentation available in github

NBTList

me.dpohvar.powernbt.api.NBTList
this class represents net.minecraft.server.NBTTagList
you can work with nbt list as with lazy java.util.List<Object>

Difference from java.util.List

• NBTList can contains only values of types:
  Byte, Short, Integer, Long, Float, Double, byte[], String, NBTList, NBTCompound, int[]
  But you can put to compound any value that can be converted to types above
  Boolean will be converted to Byte (0, 1),
  java.util.Collection and Object[] will be converted to NBTList,
  java.util.Map will be converted to NBTCompound

• Methods which add items into list creates a copy of tag:
  See example:

  NBTList list = new NBTList(); // []
  NBTList list2 = new NBTList(Arrays.asList(1,2,3)); // [1, 2, 3]
  list.add(list2);  // add a copy of list2 to list
  list2.clear(); // list2 = []
  System.out.print("list"); // [[1, 2, 3]]
  list2 = list.get(0); // Now list2 refers to a inner list
  list2.clear();
  System.out.print("list"); // [[]]
  

• NBTList can not contain cross-references:
  Example:

  NBTList list = new NBTList(); // list = []
  list.add(list); // list = [[]]
  list.add(list); // list = [[], [[]]]
  

• NBTList can not contain empty values:
  Example:

  NBTList list = new NBTList(Arrays.asList(1,2,3)); // [1, 2, 3]
  list.add(null); // do nothing
  System.out.println(list); // [1, 2, 3]
  list.set(1,null); // remove element in index 1
  System.out.println(list); // [1, 3]
  

• NBTList must contain elements of the same type.
  In most cases, it will try to convert your value.
  See Tag Type in NBT Format
  Example:

  NBTList list = new NBTList(); // list.getType() == 0
  // when type is 0 you can put to list any values
  list.add( (short) 10 ); // list.getType() == 2
  // type is 2. List can contain shorts only
  list.add( 76543 ); // convert 76543 to short and add to list
  System.out.println(list); // [10, 11007]
  list.clear(); // now list.getType() == 0 again
  list.add(new ArrayList); // now list.getType() == 9
  list.add("some String"); // NBTConvertException: can't convert String to NBT type 9
  

Convert NBTList to java.util.Collection

HashSet<Object> set = nbtList.toCollection(new HashSet<Object>());
ArrayList<Object> list = nbtList.toArrayList();

now set and list contains only java Values:
Byte, Short, Integer, Long, Float, Double, byte[], String, List, Map, int[]

Convert java.util.Collection to NBTList

NBTList list = new NBTList(collection);

But be sure, that collection does not contain cross-references!

Full documentation available in github