Tutorial 3: Managing files and folders
This tutorial shows how to access files and folders in an iHub volume and get details about these items. The resources for this task require an authId as an input parameter. The previous tutorial showed how to get an authId value.
Task 1: Get the available folders
Request the list of folders in the root directory in an iHub volume using the GET folders resource. For jQuery, form this request using a getJSON object. Parse the response object for the TotalCount field, which is the number of folders in the root directory. Then, create an HTML formatted string to display the number of folders in the output div.
1 Using BIRT Designer Professional, open the HTML file that you created in Tutorial 2: Logging in to an iHub volume.
2 Add a getfolders button after the definition of the login and reset buttons in the logintab div element, as shown in the following code:
<button id="getfolders">Get folder list</button><br /><br />
3 After the definition of uriLogin, create a new variable for the path to the folders resource:
var uriFolders = 'http://mymachine:5000/ihub/v1/folders';
4 After the code that processes the login button click, add code to process the getfolders button click. Add the following functions to run the GET folders resource request and display the output:
// Process get folders button
$( '#getfolders' ).click( function(){ getFolderList()});
 
function getFolderList() {
var request = uriFolders + '?authId=' + authId;
$.getJSON(request, function(data) { buildFolderList(data)});
}
 
function buildFolderList( data ) {
$( '#output' ).html( "Found " + data.TotalCount +
" folders.<br />" );
$.each( data.ItemList.File, function( i, item ) {
$( '#output' ).append( item.Name + '<br/>' );
});
}
5 Save and run the HTML file:
1 Choose File➛Save.
2 Copy this file into a web application deployed to a web server. Then, type the URL of the page into a web browser. Alternatively, double-click the file in Windows Explorer. In username, type:
Administrator
3 Choose Login. Choose Get folder list. The list of files appears as shown in Figure 15‑9.
Figure 15‑9 Listing folders in the root folder using the REST API
Task 2: Get details of an individual folder
Create a selection list of the folders. Get the contents of the folder. Then, get its access control list.
1 Create the selection list of folders:
1 Add a label and a selection list after the definition of the getfolders button in the logintab div element, as shown in the following code:
<label>folder:</label>
<select id="folderDropdownList" class="stringInfoSpacing">
<option value="-1" selected="selected">Use Get folder list
</option>
</select>
2 Create a variable to hold the list of folders. Populate the selection list in the code that processes the getfolders button click, as shown in the following code:
var folderIdArray = new Array();
function buildFolderList( data ) {
$( '#output' ).html( "Found " + data.TotalCount +
" folders.<br />" );
$( "#folderDropdownList" ).empty();
$.each( data.ItemList.File, function( i, item ) {
$( '#output' ).append( item.Name + '<br/>' );
folderIdArray[i] = item.Id;
$( "<option value=\'" + i + "\'>" + item.Name +
"</option>" ).appendTo( "#folderDropdownList" );
});
};
3 Add the following code to the resetAll( ) method to clear the folder list:
$( "#folderDropdownList" ).val( -1 );
4 Save and run the file, as in the previous task. Choose Get folder list. The selection list appears as shown in Figure 15‑10.
Figure 15‑10 Preparing to select folders using the REST API
2 Retrieve and display the contents of the folder:
1 After the code that processes the getfolders button click, handle selecting a value from the selection list, as shown in the following code:
var folderIndex = 0;
// Handle folder field change
$( '#folderDropdownList' ).change( function() {
folderIndex = $( this ).val();
});
2 Add a getfolderdetails button after the definition of the selection list in the logintab div element, as shown in the following code:
<button id="getfolderdetails">Get folder details</button>
<br /><br />
3 After the code that processes the selection from the list, add the following code to process the getfolderdetails button click:
// Process get folder details button
$( '#getfolderdetails' ).click( function(){
getFolderItems();
});
4 After the function that builds the folder list, add the following functions to run the GET folders/{folderId}/items resource and display an ordered list of the folder contents:
function getFolderItems() {
var request = uriFolders + '/' + folderIdArray[folderIndex] + '/items?authId=' + authId;
$.getJSON( request, function( data ) { buildFolderItemsList( data )});
}
 
function buildFolderItemsList( data ) {
if( JSON.stringify( data.ItemList ) === '{}' ){
$( '#output' ).html( "No items in folder.<br />" );
}else{
$( '#output' ).html( "Items in folder:<br />" ).append( $( '<ol>' ));
$.each( data.ItemList.File, function( i, item ){
$( '#output ol' ).append( $( '<li>' ).text( item.Name ));
});
}
}
5 Save and run the file, as in the previous task. The list of files appears as shown in Figure 15‑11.
Figure 15‑11 Displaying folder contents using the REST API
3 Retrieve and display the access control list of the folder:
1 After the existing div element, add the following code to create a new div to display the list of privileges for the folder:
<div id="details">
<p></p>
<ul></ul>
</div>
2 After the function that builds the folder list, add the following functions to run the GET folders/{folderId}/privileges resource and display an unordered list of the folder contents:
function getFolderPrivs() {
var request = uriFolders + '/' + folderIdArray[folderIndex] + '/privileges?authId=' + authId;
$.getJSON( request, function( data ) { buildFolderPrivs( data )});
}
 
function buildFolderPrivs( data ) {
$( 'ul' ).empty( );
$('p').html( "The folder " + data.File.Name +
" was last modified on " + data.File.TimeStamp +
"<br />" + data.File.Name +
" has the following privileges: <br />" );
if( JSON.stringify( data.ACL ) === '{}' ){
$( 'p' ).append(
"Access Control List is empty! Administrator access only.<br />" );
}else{
$.each( data.ACL.Permission, function( i, item ) {
$( 'ul' ).append(
$( '<li>' ).text(( item.UserName ? "User " + item.UserName :
item.RoleName ? "User Group " + item.RoleName : '' ) + ": " + item.AccessRight ));
});
}
}
3 Add the following code to the resetAll( ) method to clear the privileges text and list:
$( "p" ).empty();
$( "ul" ).empty();
4 Save and run the file, as in Step 2. Select a folder from the list. Choose Get folder details. The folder details appear as shown in Figure 15‑12.
Figure 15‑12 Displaying folder details on iHub using the REST API
Task 3: Get details of the files in the selected folder
If the folder contains any files, get the file size.
1 After the definition of uriFolders, create a new variable for the path to the files resource:
var uriFiles = 'http://mymachine:5000/ihub/v1/files';
2 In the buildFolderItemsList( ) function, test whether each item in the folder is a directory. Change the following line:
$( '#output ol' ).append( $( '<li>' ).text( item.Name ));
to:
if( item.FileType === 'Directory' ){
$( '#output ol' ).append( $( '<li>' ).text( item.Name +
" - a Directory" ));
}
3 In the buildFolderItemsList( ) function, run a files command to find the size of an item that is not a directory. After the code you added in the previous step, add the following else clause:
else{
var request = uriFiles + '/' + item.Id + '?authId=' + authId;
$.getJSON( request, function( data ) { $( '#output ol' ).append( $( '<li>' ).text( item.Name + " Size: " + data.File.Size )); });
}
4 Save and run the file, as in Task 2: Get details of an individual folder. Select a folder from the list. Choose Get folder details. The folder and file details appear as shown in Figure 15‑13.
Figure 15‑13 Displaying file details on iHub using the REST API
A complete set of code for this example is provided in Listing 15‑2. Copy and paste this code into a text editor to create the complete example. To run the example, change mymachine to the fully qualified domain name of your REST API server.
Listing 15‑2 An Actuate REST API sample folder access page using JQuery
<html>
<head>
<meta charset="utf-8" />
<script src="jquery.js"></script>
<script src="css/jquery-ui.js"></script>
<link rel="stylesheet" href="css/jquery-ui.css" />
</head>
 
<body onLoad="resetAll( )">
<h1>REST App Project</h1><hr>
<div id="logintab">
username: <input type="text" id="input_username" placeholder="Required"/><br />
password: <input type="text" id="input_password" /><br />
<br />
<button id="login">Log in</button>&nbsp;&nbsp;&nbsp;&nbsp;
&nbsp;<button id="reset">Reset</button><br /><br />
<button id="getfolders">Get folder list</button><br /><br />
<label>folder:</label>
<select id="folderDropdownList" class="stringInfoSpacing">
<option value="-1" selected="selected">
Use Get folder list</option>
</select>
<button id="getfolderdetails">Get folder details</button>
<br /><br />
</div>
 
<script type="text/javascript">
var uriLogin = 'http://mymachine:5000/ihub/v1/login';
var uriFolders = 'http://mymachine:5000/ihub/v1/folders';
var uriFiles = 'http://mymachine:5000/ihub/v1/files';
var authId;
var username;
var password;
var loginacc = {
'username':'',
'password':''
};
 
// Reset all page data
$( '#reset' ).click( function ( ) { resetAll( ) });
 
// handle username field change
$( '#input_username' ).keyup( function( ) {
username = $( this ).val( );
});
 
// handle password field change
$( '#input_password' ).keyup( function( ) {
password = $( this ).val( );
});
 
// process login button
$( '#login' ).click( function( ){
if( password ){
loginacc = {
'username':username,
'password':password
}
} else {
loginacc = {
'username':username,
'password':''
}
};
$.ajax({
type: 'POST',
data: JSON.stringify( loginacc ),
url: uriLogin,
contentType: 'application/json; charset=utf-8',
dataType: 'json',
success: function( data ) {
authId = data.AuthId;
$( '#output').html( "Login success<br/>User : " + data.User.Name + "<br/>authId: " + data.AuthId );
}, error: function () {
$( '#output').html( "Login failure <br/>User : " + username );
$( 'input:text' ).val("");
}
});
});
 
// Process get folders button
$( '#getfolders' ).click( function(){ getFolderList()});
 
var folderIndex = 0;
// Handle folder field change
$( '#folderDropdownList' ).change( function() {
folderIndex = $( this ).val();
});
 
// Process get folder details button
$( '#getfolderdetails' ).click( function(){
getFolderItems();
});
 
function getFolderList() {
var request = uriFolders + '?authId=' + authId;
$.getJSON( request, function( data ) { buildFolderList( data )});
}
 
var folderIdArray = new Array();
function buildFolderList( data ) {
$( '#output' ).html( "Found " + data.TotalCount +
" folders.<br />" );
$( "#folderDropdownList" ).empty();
$.each( data.ItemList.File, function( i, item ) {
$( '#output' ).append( item.Name + '<br/>' );
folderIdArray[i] = item.Id;
$( "<option value=\'" + i + "\'>" + item.Name +
"</option>" ).appendTo( "#folderDropdownList" );
});
}
 
function getFolderItems() {
var request = uriFolders + '/' + folderIdArray[folderIndex] + '/items?authId=' + authId;
$.getJSON( request, function( data ) { buildFolderItemsList( data )});
}
 
function buildFolderItemsList( data ) {
if( JSON.stringify( data.ItemList ) === '{}' ){
$( '#output' ).html( "No items in folder.<br />" );
}else{
$( '#output' ).html( "Items in folder:<br />" ).append( $( '<ol>' ));
$.each( data.ItemList.File, function( i, item ){
if( item.FileType === 'Directory' ){
$( '#output ol' ).append( $( '<li>' ).text( item.Name + " - a Directory" ));
}else{
var request = uriFiles + '/' + item.Id + '?authId=' + authId;
$.getJSON( request, function( data ) {
$( '#output ol' ).append( $( '<li>' ).text(
item.Name + " Size: " + data.File.Size )); });
}
});
}
}
 
function getFolderPrivs() {
var request = uriFolders + '/' + folderIdArray[folderIndex] + '/privileges?authId=' + authId;
$.getJSON( request, function( data ) { buildFolderPrivs( data )});
}
 
function buildFolderPrivs( data ) {
$( 'ul' ).empty( );
$('p').html( "The folder " + data.File.Name +
" was last modified on " + data.File.TimeStamp +
"<br />" + data.File.Name +
" has the following privileges: <br />" );
if( JSON.stringify( data.ACL ) === '{}' ){
$( 'p' ).append(
"Access Control List is empty! Administrator access only.<br />" );
}else{
$.each( data.ACL.Permission, function( i, item ) {
$( 'ul' ).append(
$( '<li>' ).text(( item.UserName ? "User " + item.UserName :
item.RoleName ? "User Group " + item.RoleName : '' ) + ": " + item.AccessRight ));
});
}
}
 
function resetAll() {
$( 'input:text' ).val( "" );
$( "#folderDropdownList" ).val( -1 );
$( '#output' ).empty( );
$( 'p' ).empty( );
$( 'ul' ).empty( );
}
 
</script>
<div id="output"></div>
<div id="details">
<p></p>
<ul></ul>
</div>
</body>
</html>