com.sap.security.core.server.vsi.api
Interface VSIService

public interface VSIService

Virus Scan Provider service main class.

This is the main service interface of the JAVA service "Virus Scan Provider".
It provides access to external virus scan products (VSA) by SAP.

More detailed information about how to integrate the Virus Scan into own developed applications can be found in SAP Note 817623.

Questions about own virus scan implementions can be posted into the SAP Developer Network (SDN) in the Security Forum.

Note:

This service main class will provide a scan Instance to the callee or null.
The return of null means that the requested Profile is not active, which further means that a virus scan should not be performed. A returned instance handle must be released at the end. So you have to work with a try/catch block and release the instance in the finally block. Call here releaseInstance(Instance vsInstance)

Example:

     VSIService vsiService=null;
     Context ctx = new InitialContext();
     // The lookup for the interface reference.
     Object obj = ctx.lookup(VSIService.JNDI_NAME);
     if(obj==null) // service not started
         return;
     else
         vsiService = (VSIService)obj;
     Instance vsiInstance=null;
     try {
          // get the instance by an own defined profile
          vsiInstance = vsiService.getInstance("ZMyScanProfile");
          if(vsiInstance==null) // the profile "ZMyScanProfile"  
             return;            // is not active, which means
                                // no scan action should be done!!!
          // we got a instance therefore perform here any scan/clean
          vsiInstance.scanBytes(Virus.EICAR); // for example
     } catch( Exception e ) {
          // we catch all. normally these exceptions would be thrown.
          // -- VirusScanException
          // -- VirusInfectionException
          // -- VSIServiceException
 
          // log the exception
          String errorText = e.getLocalizedMessage();
     } finally {
          // release instance if service is started
          if(vsiService!=null)
             vsiService.releaseInstance(vsiInstance);
     }
  

Copyright

  This software is the confidential and proprietary information
  of SAP AG, Walldorf. You shall not disclose such Confidential
  Information and shall use it only in accordance with the terms
  of the license agreement you entered into with SAP.
  

  Copyright (c) 2004-2006 SAP AG. All rights reserved.
  

History:

     1.0      Initial Version for SAP NetWeaver 04
     1.1      Added a pattern for clean test.
     1.5      Enhancements in the native VSI layer
     1.6      Dual runtime support (JAVA standalone and J2EE)
	

Since:

1.0

Version:

1.6, $DateTime: 2007/03/27 12:26:05 $

See Also:

Instance

Field Summary

static java.lang.String	JNDI_NAME The name of the VSI Service in the SAP J2EE Engine.
static java.lang.String	JVSI_NAME The name of the java virus scan interface (VSI)
static int	VSIMajorVersion This information can be used for features in the future
static int	VSIMinorVersion This information can be used for features in the future

Method Summary

Group	getGroup() Get the default group object.
Group	getGroup(int vsIndex) Get a group object.
Group	getGroup(java.lang.String vsGroupName) Get a group object.
java.lang.String[]	getGroups() Return a String[] array containing the names of the groups which are configured.
Instance	getInstance() Get a scan instance from the default scan profile.
Instance	getInstance(int vsIndex) Get a scan instance from scan profile.
Instance	getInstance(java.lang.String vsProfileName) Get a scan instance from scan profile.
Instance	getInstanceByGroup() Get a scan instance from either the default scan group.
Instance	getInstanceByGroup(int vsIndex) Get a scan instance from scan group.
Instance	getInstanceByGroup(java.lang.String vsGroupName) Get a scan instance from scan group.
Instance	getInstanceByProvider() Get a scan instance from the default provider.
Instance	getInstanceByProvider(int vsIndex) Get a scan instance from scan provider.
Instance	getInstanceByProvider(java.lang.String vsProviderName) Get a scan instance from scan provider.
Profile	getProfile() Get the default scan profile.
Profile	getProfile(int vsIndex) Get a profile object.
Profile	getProfile(java.lang.String vsProfileName) Get the requested profile object.
java.lang.String[]	getProfiles() Return a String[] array containing the names of the profiles which are available (active and not active).
Provider	getProvider() Get the default provider.
Provider	getProvider(int vsIndex) Get the provider object.
Provider	getProvider(java.lang.String vsProviderName) Get the requested provider object.
java.lang.String[]	getProviders() Return a String[] array containing the names of the providers which are active (means available).
void	releaseInstance(Instance vsInstance) Release the instance back to the instance pool.

Field Detail

VSIMajorVersion

public static final int VSIMajorVersion

This information can be used for features in the future

VSIMinorVersion

public static final int VSIMinorVersion

This information can be used for features in the future

JNDI_NAME

public static final java.lang.String JNDI_NAME

The name of the VSI Service in the SAP J2EE Engine. This constant must be used to look up the service in JNDI.

JVSI_NAME

public static final java.lang.String JVSI_NAME

The name of the java virus scan interface (VSI)

Method Detail

getProviders

public java.lang.String[] getProviders()

Return a String[] array containing the names of the providers which are active (means available).
If no provider is available you will receive an empty array.

Returns:

String[] object of provider names

getGroups

public java.lang.String[] getGroups()

Return a String[] array containing the names of the groups which are configured.
If no group is available you will receive an empty array.

Returns:

String[] object of scan group names

getProfiles

public java.lang.String[] getProfiles()

Return a String[] array containing the names of the profiles which are available (active and not active).
If no profile is available you will receive an empty array.

Returns:

String[] object of profile names

getGroup

public Group getGroup(int vsIndex)
               throws VSIServiceException

Get a group object. Scan groups combine several virus scan providers.

Parameters:

vsIndex - Index of the group.

Returns:

The Group of Index vsIndex.

Throws:

VSIServiceException - All other problems.

See Also:

Group

getGroup

public Group getGroup(java.lang.String vsGroupName)
               throws VSIServiceException

Get a group object. Scan groups combine several virus scan providers.

Parameters:

vsGroupName - Name of the group.

Returns:

The Group with name vsGroupName.

Throws:

VSIServiceException -

See Also:

Group

getGroup

public Group getGroup()
               throws VSIServiceException

Get the default group object.

Returns:

The default Group

Throws:

VSIServiceException - All other problems.

See Also:

Group

getProvider

public Provider getProvider(int vsIndex)
                     throws VSIServiceException

Get the provider object.

Parameters:

vsIndex - Index of the provider in the list.

Returns:

Provider object

Throws:

VSIServiceException -

See Also:

Provider

getProvider

public Provider getProvider(java.lang.String vsProviderName)
                     throws VSIServiceException

Get the requested provider object.

Parameters:

vsProviderName - Name of the provider to be returned.

Returns:

Provider object.

Throws:

VSIServiceException - All other problems.

See Also:

Provider

getProvider

public Provider getProvider()
                     throws VSIServiceException

Get the default provider.

Returns:

Default provider object.

Throws:

VSIServiceException - All other problems.

See Also:

Provider

getProfile

public Profile getProfile(int vsIndex)
                   throws VSIServiceException

Get a profile object.

Parameters:

vsIndex - Index of the profile in the list.

Returns:

Profile object

Throws:

VSIServiceException - All other problems.

See Also:

Profile

getProfile

public Profile getProfile(java.lang.String vsProfileName)
                   throws VSIServiceException

Get the requested profile object.

Parameters:

vsProfileName - Name of the Profile

Returns:

Profile object

Throws:

VSIServiceException - All other problems.

See Also:

Profile

getProfile

public Profile getProfile()
                   throws VSIServiceException

Get the default scan profile.

Returns:

Default profile object Profile

Throws:

VSIServiceException -

See Also:

Profile

getInstance

public Instance getInstance()
                     throws VSIServiceException

Get a scan instance from the default scan profile.

Returns:

A pooled Instance class handle.

Throws:

VSIServiceException - All other problems.

See Also:

getInstance(String)

getInstance

public Instance getInstance(java.lang.String vsProfileName)
                     throws VSIServiceException

Get a scan instance from scan profile. This method is the only method which might return null.

This behaviour is wanted. If a profile is "not active" then you will get here null and should return in your own scan method. If you receive a handle != null then you "should" perform a scan action here.

Therefore this different behaviour should act as on/off switch for a virus scan action.

Note: This is the only method which might return null. All other methods wont return null but will throw an exception.

Parameters:

vsProfileName - Name of the pref-configured scan profile. A virus scan profile contains at least one scan group and/or profile to provide your own security workflow and load balancing mechanism.

Returns:

A pooled Instance class handle or null.
If this method returns null, the profile is not active and an application should not perform a scan.

Throws:

VSIServiceException - All other problems.

getInstance

public Instance getInstance(int vsIndex)
                     throws VSIServiceException

Get a scan instance from scan profile.

Parameters:

vsIndex - Index of the scan profile.

Returns:

A pooled Instance class handle.

Throws:

VSIServiceException - All other problems.

See Also:

getInstanceByGroup(String)

getInstanceByGroup

public Instance getInstanceByGroup()
                            throws VSIServiceException

Get a scan instance from either the default scan group.

Returns:

A pooled Instance class handle.

Throws:

VSIServiceException - All other problems.

See Also:

getInstanceByGroup(String)

getInstanceByGroup

public Instance getInstanceByGroup(java.lang.String vsGroupName)
                            throws VSIServiceException

Get a scan instance from scan group.

Parameters:

vsGroupName - Name of the pref-configured scan group. A virus scan group contains several scan providers to provide a load balancing mechanism.

Returns:

A pooled Instance class handle.

Throws:

VSIServiceException - All other problems.

getInstanceByGroup

public Instance getInstanceByGroup(int vsIndex)
                            throws VSIServiceException

Get a scan instance from scan group.

Parameters:

vsIndex - Index of the scan group.

Returns:

A pooled Instance class handle.

Throws:

VSIServiceException - All other problems.

See Also:

getInstanceByGroup(String)

getInstanceByProvider

public Instance getInstanceByProvider()
                               throws VSIServiceException

Get a scan instance from the default provider.

Returns:

A new Instance class handle.

Throws:

VSIServiceException - All other problems.

See Also:

getInstanceByProvider(String)

getInstanceByProvider

public Instance getInstanceByProvider(java.lang.String vsProviderName)
                               throws VSIServiceException

Get a scan instance from scan provider.

Parameters:

vsProviderName - Name of the pref-configured provider. A virus scan provider can either be a Virus Scan Server or a virus scan adapter. The last one needs a native adapter library.

Returns:

A pooled Instance class handle.

Throws:

VSIServiceException - All other problems.

getInstanceByProvider

public Instance getInstanceByProvider(int vsIndex)
                               throws VSIServiceException

Get a scan instance from scan provider.

Parameters:

vsIndex - Index of the provider to be returned.

Returns:

A pooled Instance class handle.

Throws:

VSIServiceException - All other problems.

See Also:

getInstanceByProvider(String)

releaseInstance

public void releaseInstance(Instance vsInstance)

Release the instance back to the instance pool.

Note: Call this method always in the finally block. You can also pass null instance handles, therefore you should call this method in any cases after you have requested for an instance object.

Parameters:

vsInstance - Instance object to be released.

See Also:

Instance