Sometimes I want to write a program something just for the sake of doing it. So I decided to write a simple Java client for Vault. As you may already know, Vault communicates over HTTP using SOAP, which means you can write a client in just about any language and platform that you want.
The program itself is pretty basic. It's just a Java port of the VaultList SDK sample, which just lists all the files in the Vault.
If you are a member of the Autodesk Developer Network, you should read Tutorial: Using Java to Access the Vault API, which is the definitive guide to writing Java clients for Vault. Although it was written for Vault 5, it's still valid for Vault 2010.
I tried using some of the newer Java tools for web services, but I was not able to get them to work properly with Vault. The problem was getting control of the security header, which needs to be copied from the SecurityService to all the other services. Axis 1.4 gave me the ability to do that, but I was not able to find a way with JAX-WS or Axis 2. Of course, my Java is very rusty, so maybe I just missed how to do it.
Vault Mirror holds a special place in my heart. It's the first utility I ever released publicly, and it was one of the first utilities to be featured on Autodesk Labs. It took me only a few hours to write, and I figured it would have a short lifetime.
Much to my delight, the utility is still in use today by many people, and in ways that I never imagined. Brian Schanen has already blogged about this, but I want to add my own technical perspective.
What is Vault Mirror?
It's a utility that downloads all the files from Vault for read-only purposes. It was designed to be automated, lightweight and efficient. It works with the base version of Vault, and it won't consume a license in the pay-for versions.
Vault Mirror does not create a perfect replica of a Vault. It only downloads the latest version of the files. Other things like items, properties, file history, security, lifecycle states etc. are not copied.
Where can I get it?
It's installed with the Vault Server, but you have to dig a bit in the SDK to find it. The folder location is [ADMS dir]\SDK\VS8\CSharp\VaultMirror\bin\Release
Update: In Vault 2011, the utility has been moved to a new location [ADMS dir]\SDK\util\VaultMirror
The readme (and source code) can be found two levels higher. Feel free to copy things to a more convenient location.
Uses for Vault Mirror:
If you found a use not mentioned in the list below, please let us know by posting it in the comments section.
Full Mirror command:
The full mirror command will basically synchronize your windows folders to match the Vault folder. Be warned, this includes deleting local files/folders if it there is not a match in the Vault.
The algorithm works by going through the Vault folder-by-folder and comparing the Vault files with the files on disk. If a file exists in the Vault but not on disk, the file is downloaded. If a file exists on disk but not in the Vault, the local file is deleted. If a file exists on disk and in the Vault, the checksum is compared. If the local file has a different checksum as the Vault file, the local file is overwritten.
In practice, this command is only used to clean up things. It may take a long time to run depending on the size of the Vault, so this command should be run rarely if ever.
Partial Mirror command:
The partial mirror command will basically download all new files. Any new file is downloaded. No effort is made to clean up the local folder.
The algorithm works by doing a file search. Vault Mirror remembers when the last, time a command was run, so it searches all file versions created after the time of the last search. Any matching files are downloaded.
Since only new files are downloaded, this is a very scalable command. It's no problem to run this command every few minutes so that your mirror folder is mostly up-to-date.
Since its release, Vault has added a lot of features that I thought would make Vault Mirror obsolete. However the utility is still in use. Maybe people don't know about the other features, maybe they like Vault Mirror better, or maybe there is some aspect of the built-in feature that makes it unusable. Whatever the reason, I thought I should list the features that Vault Mirror "competes" against. That way you can choose the utility or feature that works best for you.
Client-server communication in Vault is done via HTTP connections. This means that Vault can be set up with various HTTP features. Some of those features may keep your client from connecting, so let's go over how to handle things when the server is on SSL or a non-standard port.
Connecting on a different port
You can change your IIS settings to use a different port than 80. At the API level, you handle this when you set the URL on your web service object. For example, if you are using port 2112, you would set your DocumentService.URL value to http://servername:2112/AutodeskDM/Services/DocumentService.asmx
For login dialogs, Autodesk clients use the convention of adding the port to the end of the server name. For example, "servername:2112".
Connecting via SSL
If you have your server configured for SSL, you still handle things with the URL property. In this case your, DocumentService.URL would have the value of https://servername/AutodeskDM/Services/DocumentService.asmx
For login dialogs, the Autodesk convention is to have "https://" before the server name. For example, "https://servername".
Connecting via SSL on a different port
The default SSL port is 443. If you are using SSL on a different port, you can just combine the rules from above. For example: https://servername:2112/AutodeskDM/Services/DocumentService.asmx
The VaultFileBrowser sample in the SDK handles these cases. So feel free to borrow that code. The login dialog assumes the same server name syntax as the rest of the Autodesk clients.
So, your program encountered an error, and the Vault Server returns error 0, which means "UnspecifiedSystemException". Here is how you deal with it.
Error 0 is our "catch all" error. It means that you did something that caused an Exception that we here at Autodesk didn't expect. So the Exception bubbled up to the top of the stack and resulted in error 0 getting passed back to your program.
Getting more information:
The best thing to do is to find the vlog file on the server. This file logs all server errors, including the error 0 you just ran into. You can find the vlog in your file store folder (ex. C:\Documents and Settings\All Users\Application Data\Autodesk\VaultServer\FileStore). There will be several vlog files, since a new one is created each day.
Open today's file and scroll down until you find your error. I will look something like this:
Error: Soap Exception ( mesg-id = 633969862478903845 )
Exception(Inner): Could not load type 'Connectivity.Core.DataAccess.IEditStatusBuilder' from assembly 'Connectivity.Platform, Version=220.127.116.11, Culture=neutral, PublicKeyToken=null'.
Exception rethrown at :
This is basically the stack trace of the Exception as it is seen on the server. Sometimes you can figure out the problem from the inner exception. For example, if it's a NullReferenceException maybe it's due to some null data you passed in. But most of the time it will just look like useless gibberish, which brings me to my next point.
Getting in touch with us:
Ideally Vault Server should be passing back something back more descriptive than 0. If you run into it, let us know. The best places are through the Autodesk Developer Network or on the Vault newsgroup. Make sure to tell us what you were doing and include the appropriate section from the vlog.