File Support

As noted in the readme, files are represented in the Gravity by the abstract Gravity.Base.FileDto class. There are two different implementations of this class, representing two different storage mechanisms:

• Gravity.Base.ByteArrayFileDto stores the file data in memory.
  • When a file is read from the API, its name and raw bytes are copied into this object.
  • When a file is written to the API, the bytes are uploaded into a file of the given name.
• Gravity.Base.DiskFileDto represents a file location on the disk.
  • This type does not support API reads. If you attempt to read into a field with this type, you will get an exception.
  • On API writes, a stream reading the referenced file is supplied to the underlying API.

On your BaseDto object, you can specify the type of your field type as FileDto or either child type. API write operations can write either child type, but the API always reads file fields as ByteArrayFileDto (so, as noted above, not not read into a DiskFileDto field.

Here are the public signatures of the types:

public class DiskFileDto : FileDto
{
	string FilePath { get; set; }
	ByteArrayFileDto StoreInMemory();
}
public class ByteArrayFileDto : FileDto
{
	byte[] ByteArray { get; set; }
	string FileName { get; set; }
	DiskFileDto WriteToFile(string filePath);
}

As you can see, each type has a method for converting to the other type. This is particularly handy for unloading API-read files from memory:

var myObject = rsapiProvider.Get<MyType>(1, ObjectFieldsDepthLevel.ParentOnly);
var fileFieldValue = (ByteArrayFileDto)myObject.FileField;
myObject.FileField = fileFieldValue.WriteToFile(Path.Join(@"\\Repository", fileFieldValue.FileName));

Some more notes on read/write behavior:

• If the field is set to null, the file is removed from Relativity on the next write operation.
• To reduce API traffic, the MD5 of the file content is cached after each read or write call. The file is then uploaded on the next write call if and only if the MD5 has changed.
  • This means that the file name will only be updated if the file contents are updated also. To rename a file in Relativity, you will have to clear the field and then re-set it.
  • The file will always be re-read from the server on read operations.